@snaptrude/plugin-core 0.3.0 → 0.6.0

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

@@ -0,0 +1,427 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+/**
+ * Buildings — read and edit the buildings of the active project.
+ *
+ * A **building** is the top of the project's spatial hierarchy: a named container
+ * of storeys, positioned by its base elevation. This namespace reads a building's
+ * identity and base elevation and lists the storeys it holds; storey detail is
+ * read through the entity story surface (`snaptrude.entity.story`).
+ *
+ * Reads return plain records and never throw for a missing building (`get` and
+ * `getActive` return `null`, `list` returns `[]`). 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.buildings`.
+ */
+export declare abstract class PluginCoreBuildingsApi {
+    constructor();
+    /**
+     * List the buildings in the active project.
+     *
+     * @returns A {@linkcode PluginCoreBuildingsListResult} with a `buildings` array
+     *   (empty when the project has none).
+     *
+     * @examplePrompt List all the buildings in my project
+     * @examplePrompt How many buildings are in this model?
+     * @examplePrompt Show every building with its base elevation
+     *
+     * # Example
+     * ```ts
+     * const { buildings } = await snaptrude.core.buildings.list()
+     * for (const b of buildings) console.log(b.name, b.baseElevation)
+     * ```
+     */
+    abstract list(): PluginApiReturn<PluginCoreBuildingsListResult>;
+    /**
+     * Get a single building by id.
+     *
+     * @param buildingId - The id of the building to read.
+     * @returns The matching {@linkcode PluginCoreBuildingRef}, or `null` if no
+     *   building has that id.
+     *
+     * @examplePrompt Get the building with id blg_1
+     * @examplePrompt Look up a single building by its id
+     * @examplePrompt What is the base elevation of building blg_2?
+     *
+     * # Example
+     * ```ts
+     * const building = await snaptrude.core.buildings.get("blg_1")
+     * if (building) console.log(building.name, building.baseElevation)
+     * ```
+     */
+    abstract get(buildingId: string): PluginApiReturn<PluginCoreBuildingsGetResult>;
+    /**
+     * List the storeys of a building.
+     *
+     * Returns the building's storeys as stable storey ids, in the project's storey
+     * order. Read each storey's detail through `snaptrude.entity.story`.
+     *
+     * @param buildingId - The id of the building whose storeys to list.
+     * @returns A {@linkcode PluginCoreBuildingsListStoreysResult} with a `storeyIds`
+     *   array (empty when the building is missing or has no storeys).
+     *
+     * @examplePrompt List the storeys in building blg_1
+     * @examplePrompt How many floors does this building have?
+     * @examplePrompt Get the storey ids of the active building
+     *
+     * # Example
+     * ```ts
+     * const { storeyIds } = await snaptrude.core.buildings.listStoreys("blg_1")
+     * console.log(`${storeyIds.length} storeys`)
+     * ```
+     */
+    abstract listStoreys(buildingId: string): PluginApiReturn<PluginCoreBuildingsListStoreysResult>;
+    /**
+     * Get the active building.
+     *
+     * The active building is the one new storeys and edits target. Paired with
+     * {@linkcode PluginCoreBuildingsApi.setActive}.
+     *
+     * @returns A {@linkcode PluginCoreBuildingsGetActiveResult} with the active
+     *   `buildingId`, or `null` if there is no active building.
+     *
+     * @examplePrompt Which building is active?
+     * @examplePrompt Get the current building
+     * @examplePrompt What building am I working in?
+     *
+     * # Example
+     * ```ts
+     * const active = await snaptrude.core.buildings.getActive()
+     * if (active) console.log(active.buildingId)
+     * ```
+     */
+    abstract getActive(): PluginApiReturn<PluginCoreBuildingsGetActiveResult>;
+    /**
+     * Make a building the active building.
+     *
+     * Paired with {@linkcode PluginCoreBuildingsApi.getActive}.
+     *
+     * @param buildingId - The id of the building to activate.
+     * @returns The id of the now-active building.
+     * @throws If no building has the given id.
+     *
+     * @examplePrompt Switch to building blg_2
+     * @examplePrompt Make this building the active one
+     * @examplePrompt Set the active building to blg_1
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.core.buildings.setActive("blg_2")
+     * ```
+     */
+    abstract setActive(buildingId: string): PluginApiReturn<PluginCoreBuildingsSetActiveResult>;
+    /**
+     * Create a new building.
+     *
+     * Adds a named building at the given base elevation (defaults to `0`). The new
+     * building starts empty — add storeys through the storeys namespace.
+     *
+     * @param name - Display name of the new building.
+     * @param baseElevation - Base elevation in meters (defaults to `0`).
+     * @returns The new building's id (read the full record back with
+     *   {@linkcode PluginCoreBuildingsApi.get}).
+     * @throws If the building could not be created.
+     *
+     * @examplePrompt Create a building called Tower B
+     * @examplePrompt Add a new building at elevation 12 meters
+     * @examplePrompt Make a second building named Annex
+     *
+     * # Example
+     * ```ts
+     * const { buildingId } = await snaptrude.core.buildings.create("Tower B", 0)
+     * ```
+     */
+    abstract create(name: string, baseElevation?: number): PluginApiReturn<PluginCoreBuildingsCreateResult>;
+    /**
+     * Update a building's name and/or base elevation.
+     *
+     * A **sparse** update: omitted fields are left unchanged.
+     *
+     * @param buildingId - The id of the building to update.
+     * @param options - Any of `name`, `baseElevation`; omitted fields are left
+     *   unchanged.
+     * @returns The updated {@linkcode PluginCoreBuildingRef}.
+     * @throws If no building has the given id.
+     *
+     * @examplePrompt Rename building blg_1 to Tower A
+     * @examplePrompt Move the building up to elevation 6 meters
+     * @examplePrompt Change the base elevation of blg_2
+     *
+     * # Example
+     * ```ts
+     * const building = await snaptrude.core.buildings.update("blg_1", { name: "Tower A" })
+     * ```
+     */
+    abstract update(buildingId: string, options?: {
+        name?: string;
+        baseElevation?: number;
+    }): PluginApiReturn<PluginCoreBuildingsUpdateResult>;
+    /**
+     * Copy a building.
+     *
+     * Copies the building — its storeys, components, and drawing layers — into a new
+     * building. `asInstances` controls the copy's geometry: `true` shares the source
+     * geometry as instances (low memory), `false` makes independent editable copies
+     * (the host defaults to `true`). Optionally override the copy's `name` and
+     * `baseElevation`.
+     *
+     * @param buildingId - The id of the building to copy.
+     * @param options - Optional `name`, `baseElevation`, `asInstances` overrides
+     *   for the copy.
+     * @returns The new building's id.
+     * @throws If no building has the given id.
+     *
+     * @examplePrompt Copy building blg_1
+     * @examplePrompt Make an independent editable copy of this building
+     * @examplePrompt Copy Tower A as instances to save memory
+     *
+     * # Example
+     * ```ts
+     * const { buildingId } = await snaptrude.core.buildings.copy("blg_1", {
+     *   name: "Tower A Copy",
+     *   asInstances: false,
+     * })
+     * ```
+     */
+    abstract copy(buildingId: string, options?: {
+        name?: string;
+        baseElevation?: number;
+        asInstances?: boolean;
+    }): PluginApiReturn<PluginCoreBuildingsCopyResult>;
+    /**
+     * Delete a building.
+     *
+     * **Gated and destructive.** Deleting a building cascades through its meshes,
+     * storeys, and the building itself, and removes its saved views — **saved views
+     * are not restored on undo.** The project's only remaining building cannot be
+     * deleted.
+     *
+     * @param buildingId - The id of the building to delete.
+     * @returns Confirmation that the building was deleted.
+     * @throws If no building has the given id, or it is the only building.
+     *
+     * @examplePrompt Delete building blg_2
+     * @examplePrompt Remove the Annex building and everything in it
+     * @examplePrompt Delete this building
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.core.buildings.delete("blg_2")
+     * ```
+     */
+    abstract delete(buildingId: string): PluginApiReturn<PluginCoreBuildingsDeleteResult>;
+}
+/**
+ * A building in the active project.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable public building id (e.g. `"blg_1"`) |
+ * | `name` | `string` | Display name |
+ * | `baseElevation` | `number` | Base elevation in meters, positive up (default `0`) |
+ */
+export declare const PluginCoreBuildingRef: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    baseElevation: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginCoreBuildingRef = z.infer<typeof PluginCoreBuildingRef>;
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildings` | {@linkcode PluginCoreBuildingRef}`[]` | Every building in the active project |
+ */
+export declare const PluginCoreBuildingsListResult: z.ZodObject<{
+    buildings: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        baseElevation: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginCoreBuildingsListResult = z.infer<typeof PluginCoreBuildingsListResult>;
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the building to read |
+ */
+export declare const PluginCoreBuildingsGetArgs: z.ZodObject<{
+    buildingId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreBuildingsGetArgs = z.infer<typeof PluginCoreBuildingsGetArgs>;
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.get} — the building, or `null` when
+ * no building has the given id.
+ */
+export declare const PluginCoreBuildingsGetResult: z.ZodNullable<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    baseElevation: z.ZodNumber;
+}, z.core.$strip>>;
+export type PluginCoreBuildingsGetResult = z.infer<typeof PluginCoreBuildingsGetResult>;
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.listStoreys}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the building whose storeys to list |
+ */
+export declare const PluginCoreBuildingsListStoreysArgs: z.ZodObject<{
+    buildingId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreBuildingsListStoreysArgs = z.infer<typeof PluginCoreBuildingsListStoreysArgs>;
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.listStoreys}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storeyIds` | `string[]` | The building's storey ids in storey order (empty when missing or none) |
+ */
+export declare const PluginCoreBuildingsListStoreysResult: z.ZodObject<{
+    storeyIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type PluginCoreBuildingsListStoreysResult = z.infer<typeof PluginCoreBuildingsListStoreysResult>;
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.getActive} — the active building's
+ * id, or `null` when there is no active building.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the active building |
+ */
+export declare const PluginCoreBuildingsGetActiveResult: z.ZodNullable<z.ZodObject<{
+    buildingId: z.ZodString;
+}, z.core.$strip>>;
+export type PluginCoreBuildingsGetActiveResult = z.infer<typeof PluginCoreBuildingsGetActiveResult>;
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the building to activate |
+ */
+export declare const PluginCoreBuildingsSetActiveArgs: z.ZodObject<{
+    buildingId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreBuildingsSetActiveArgs = z.infer<typeof PluginCoreBuildingsSetActiveArgs>;
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.setActive} — the now-active
+ * building's id.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the now-active building |
+ */
+export declare const PluginCoreBuildingsSetActiveResult: z.ZodObject<{
+    buildingId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreBuildingsSetActiveResult = z.infer<typeof PluginCoreBuildingsSetActiveResult>;
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Display name of the new building |
+ * | `baseElevation` | `number \| undefined` | Base elevation in meters (defaults to `0`) |
+ */
+export declare const PluginCoreBuildingsCreateArgs: z.ZodObject<{
+    name: z.ZodString;
+    baseElevation: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginCoreBuildingsCreateArgs = z.infer<typeof PluginCoreBuildingsCreateArgs>;
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.create} — the id of the new
+ * building.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the newly created building |
+ */
+export declare const PluginCoreBuildingsCreateResult: z.ZodObject<{
+    buildingId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreBuildingsCreateResult = z.infer<typeof PluginCoreBuildingsCreateResult>;
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.update}. Sparse — only the
+ * provided fields are changed.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the building to update |
+ * | `name` | `string \| undefined` | New display name (unchanged if omitted) |
+ * | `baseElevation` | `number \| undefined` | New base elevation in meters (unchanged if omitted) |
+ */
+export declare const PluginCoreBuildingsUpdateArgs: z.ZodObject<{
+    buildingId: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    baseElevation: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginCoreBuildingsUpdateArgs = z.infer<typeof PluginCoreBuildingsUpdateArgs>;
+/** Result of {@linkcode PluginCoreBuildingsApi.update} — the updated record. */
+export declare const PluginCoreBuildingsUpdateResult: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    baseElevation: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginCoreBuildingsUpdateResult = z.infer<typeof PluginCoreBuildingsUpdateResult>;
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.copy}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the building to copy |
+ * | `name` | `string \| undefined` | Name for the copy (auto-generated if omitted) |
+ * | `baseElevation` | `number \| undefined` | Base elevation for the copy in meters (source's if omitted) |
+ * | `asInstances` | `boolean \| undefined` | `true` shares source geometry as instances; `false` makes independent copies (host default `true`) |
+ */
+export declare const PluginCoreBuildingsCopyArgs: z.ZodObject<{
+    buildingId: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    baseElevation: z.ZodOptional<z.ZodNumber>;
+    asInstances: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type PluginCoreBuildingsCopyArgs = z.infer<typeof PluginCoreBuildingsCopyArgs>;
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.copy} — the id of the new
+ * building.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the copied building |
+ */
+export declare const PluginCoreBuildingsCopyResult: z.ZodObject<{
+    buildingId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreBuildingsCopyResult = z.infer<typeof PluginCoreBuildingsCopyResult>;
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the building to delete |
+ */
+export declare const PluginCoreBuildingsDeleteArgs: z.ZodObject<{
+    buildingId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreBuildingsDeleteArgs = z.infer<typeof PluginCoreBuildingsDeleteArgs>;
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.delete} — confirmation that the
+ * building was deleted.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `deleted` | `true` | Always `true` on success |
+ */
+export declare const PluginCoreBuildingsDeleteResult: z.ZodObject<{
+    deleted: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export type PluginCoreBuildingsDeleteResult = z.infer<typeof PluginCoreBuildingsDeleteResult>;
+//# sourceMappingURL=buildings.d.ts.map

package/dist/api/core/buildings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildings.d.ts","sourceRoot":"","sources":["../../../src/api/core/buildings.ts"],"names":[],"mappings":"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"}

package/dist/api/core/comment/index.d.ts

@@ -0,0 +1,230 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../../types";
+import { Vec3Handle, ComponentHandle } from "../../../handles";
+/**
+ * Comments — create, edit, resolve, tag, and list scene/project comments.
+ *
+ * A comment is an opaque {@link CommentHandle} (its server id). Comments may be
+ * anchored to a component at a 3D point, carry @mentions (by email) and emojis,
+ * and be resolved / reopened. Accessed via `snaptrude.core.comment`.
+ */
+export declare abstract class PluginCommentApi {
+    constructor();
+    /**
+     * Create a comment in the project — optionally pinned to a component at a 3D
+     * point — with optional @mentions that notify teammates by email.
+     *
+     * @param message - Comment text (emojis = plain unicode).
+     * @param component - Optional component to anchor the comment to.
+     * @param position - Optional pin point; defaults to the component's center.
+     * @param mentions - Optional user emails to @mention (appended as real @mention tags).
+     * @returns the new {@link CommentHandle}.
+     *
+     * @examplePrompt Add a comment on this wall saying the height looks wrong
+     * @examplePrompt Leave a note on the selected room for the design team
+     * @examplePrompt Comment "verify the door swing" and tag alex@acme.com
+     * @examplePrompt Pin a review note at this point on the slab
+     *
+     * # Example
+     * ```ts
+     * const c = await snaptrude.core.comment.create(
+     *   "Check this wall 🎉",
+     *   spaceId,
+     *   undefined,
+     *   ["alex@acme.com"],
+     * )
+     * ```
+     */
+    abstract create(message: string, component?: ComponentHandle, position?: Vec3Handle, mentions?: string[]): PluginApiReturn<CommentHandle>;
+    /**
+     * Edit a comment's message (and optional @mentions).
+     *
+     * @param comment - The comment to edit.
+     * @param message - New message text.
+     * @param mentions - Optional user emails to @mention.
+     *
+     * @examplePrompt Edit my comment to say the beam depth is 600mm
+     * @examplePrompt Change the text of this comment
+     * @examplePrompt Update the note on the wall and mention priya@studio.com
+     * @examplePrompt Reword the comment I just added
+     *
+     * # Example
+     * ```ts
+     * const c = await snaptrude.core.comment.create("Beam depth TBD")
+     * await snaptrude.core.comment.update(c, "Beam depth is 600mm", ["priya@studio.com"])
+     * ```
+     */
+    abstract update(comment: CommentHandle, message: string, mentions?: string[]): PluginApiReturn<boolean>;
+    /**
+     * Mark a comment resolved. Paired with {@link PluginCommentApi.reopen}.
+     *
+     * @param comment - The target comment.
+     *
+     * @examplePrompt Mark this comment as resolved
+     * @examplePrompt Resolve the comment about the staircase
+     * @examplePrompt Close out this review note
+     * @examplePrompt Set that comment to done
+     *
+     * # Example
+     * ```ts
+     * const c = await snaptrude.core.comment.create("Verify the door swing")
+     * await snaptrude.core.comment.resolve(c)
+     * ```
+     */
+    abstract resolve(comment: CommentHandle): PluginApiReturn<boolean>;
+    /**
+     * Reopen a resolved comment. Paired with {@link PluginCommentApi.resolve}.
+     *
+     * @param comment - The target comment.
+     *
+     * @examplePrompt Reopen this resolved comment
+     * @examplePrompt Mark the comment as unresolved again
+     * @examplePrompt Bring back the closed note about the window heights
+     * @examplePrompt Un-resolve that comment so we can keep discussing it
+     *
+     * # Example
+     * ```ts
+     * const [comment] = await snaptrude.core.comment.list()
+     * await snaptrude.core.comment.reopen(comment)
+     * ```
+     */
+    abstract reopen(comment: CommentHandle): PluginApiReturn<boolean>;
+    /**
+     * Check whether a comment has been marked resolved.
+     *
+     * @param comment - The target comment.
+     *
+     * @examplePrompt Is this comment resolved yet?
+     * @examplePrompt Check if the note about the roof has been closed
+     * @examplePrompt Has my comment been resolved?
+     * @examplePrompt Tell me whether that comment is still open
+     *
+     * # Example
+     * ```ts
+     * const [comment] = await snaptrude.core.comment.list()
+     * const resolved = await snaptrude.core.comment.isResolved(comment)
+     * console.log(resolved ? "resolved" : "still open")
+     * ```
+     */
+    abstract isResolved(comment: CommentHandle): PluginApiReturn<boolean>;
+    /**
+     * Tag (mention) a user on an existing comment, by email.
+     *
+     * @param comment - The comment to add a mention to.
+     * @param email - The user's email to @mention.
+     *
+     * @examplePrompt Tag alex@acme.com on this comment
+     * @examplePrompt Mention the structural engineer in that note
+     * @examplePrompt Add priya@studio.com to the comment about the lobby
+     * @examplePrompt Notify a teammate about an existing comment
+     *
+     * # Example
+     * ```ts
+     * const [comment] = await snaptrude.core.comment.list()
+     * await snaptrude.core.comment.tag(comment, "alex@acme.com")
+     * ```
+     */
+    abstract tag(comment: CommentHandle, email: string): PluginApiReturn<boolean>;
+    /**
+     * Permanently remove a comment from the project.
+     *
+     * @param comment - The target comment.
+     *
+     * @examplePrompt Delete this comment
+     * @examplePrompt Remove the note about the old layout
+     * @examplePrompt Get rid of my last comment
+     * @examplePrompt Clear that resolved comment off the wall
+     *
+     * # Example
+     * ```ts
+     * const [comment] = await snaptrude.core.comment.list()
+     * await snaptrude.core.comment.delete(comment)
+     * ```
+     */
+    abstract delete(comment: CommentHandle): PluginApiReturn<boolean>;
+    /**
+     * List every comment in the project (deleted ones are excluded), returned as
+     * comment handles you can pass to the other comment methods.
+     *
+     * @examplePrompt List all the comments in this project
+     * @examplePrompt How many comments are on this model?
+     * @examplePrompt Show every note in the file
+     * @examplePrompt Get all comments so I can check which are resolved
+     *
+     * # Example
+     * ```ts
+     * const comments = await snaptrude.core.comment.list()
+     * console.log(`${comments.length} comments in the project`)
+     * ```
+     */
+    abstract list(): PluginApiReturn<CommentHandle[]>;
+}
+/**
+ * Opaque handle to a comment — its server-assigned id (entity-style: a raw,
+ * persistable string resolved live, not a registry-minted value handle).
+ */
+export type CommentHandle = string & {
+    readonly __handle: "comment";
+};
+export declare const CommentHandle: z.ZodPipe<z.ZodString, z.ZodTransform<CommentHandle, string>>;
+/** `ComponentHandle` is defined in `handles.ts` (imported above) and exported from the
+ *  package root via `export * from "./handles"`. Not re-exported here to avoid an
+ *  ambiguous double `export *` at the barrel. */
+/**
+ * Arguments for {@link PluginCommentApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@link ComponentHandle}? | Component to anchor the comment to |
+ * | `position` | {@link Vec3Handle}? | Pin point; defaults to the component's center |
+ * | `message` | `string` | Comment text (emojis = unicode) |
+ * | `mentions` | `string[]`? | User emails to @mention |
+ */
+export declare const PluginCommentCreateArgs: z.ZodObject<{
+    component: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+    position: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("../../..").Handle<"vec3">, string>>>;
+    message: z.ZodString;
+    mentions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type PluginCommentCreateArgs = z.infer<typeof PluginCommentCreateArgs>;
+/**
+ * Arguments for {@link PluginCommentApi.update}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `comment` | {@link CommentHandle} | The comment to edit |
+ * | `message` | `string` | New message text |
+ * | `mentions` | `string[]`? | User emails to @mention |
+ */
+export declare const PluginCommentUpdateArgs: z.ZodObject<{
+    comment: z.ZodPipe<z.ZodString, z.ZodTransform<CommentHandle, string>>;
+    message: z.ZodString;
+    mentions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type PluginCommentUpdateArgs = z.infer<typeof PluginCommentUpdateArgs>;
+/**
+ * Arguments for {@link PluginCommentApi.resolve} / {@link PluginCommentApi.reopen}
+ * / {@link PluginCommentApi.isResolved} / {@link PluginCommentApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `comment` | {@link CommentHandle} | The target comment |
+ */
+export declare const PluginCommentRefArgs: z.ZodObject<{
+    comment: z.ZodPipe<z.ZodString, z.ZodTransform<CommentHandle, string>>;
+}, z.core.$strip>;
+export type PluginCommentRefArgs = z.infer<typeof PluginCommentRefArgs>;
+/**
+ * Arguments for {@link PluginCommentApi.tag}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `comment` | {@link CommentHandle} | The comment to add a mention to |
+ * | `email` | `string` | The user's email to @mention |
+ */
+export declare const PluginCommentTagArgs: z.ZodObject<{
+    comment: z.ZodPipe<z.ZodString, z.ZodTransform<CommentHandle, string>>;
+    email: z.ZodString;
+}, z.core.$strip>;
+export type PluginCommentTagArgs = z.infer<typeof PluginCommentTagArgs>;
+//# sourceMappingURL=index.d.ts.map

package/dist/api/core/comment/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/core/comment/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAE9D;;;;;;GAMG;AACH,8BAAsB,gBAAgB;;IAGpC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;aACa,MAAM,CACpB,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,eAAe,EAC3B,QAAQ,CAAC,EAAE,UAAU,EACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,eAAe,CAAC,aAAa,CAAC;IAEjC;;;;;;;;;;;;;;;;;OAiBG;aACa,MAAM,CACpB,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,eAAe,CAAC,OAAO,CAAC;IAE3B;;;;;;;;;;;;;;;OAeG;aACa,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,eAAe,CAAC,OAAO,CAAC;IAEzE;;;;;;;;;;;;;;;OAeG;aACa,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,eAAe,CAAC,OAAO,CAAC;IAExE;;;;;;;;;;;;;;;;OAgBG;aACa,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,eAAe,CAAC,OAAO,CAAC;IAE5E;;;;;;;;;;;;;;;;OAgBG;aACa,GAAG,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC;IAEpF;;;;;;;;;;;;;;;OAeG;aACa,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,eAAe,CAAC,OAAO,CAAC;IAExE;;;;;;;;;;;;;;OAcG;aACa,IAAI,IAAI,eAAe,CAAC,aAAa,EAAE,CAAC;CACzD;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,CAAA;AACrE,eAAO,MAAM,aAAa,+DAGa,CAAA;AAEvC;;iDAEiD;AAEjD;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB;;;;;iBAKlC,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB;;;;iBAIlC,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB;;iBAE/B,CAAA;AAEF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB;;;iBAG/B,CAAA;AAEF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA"}