@snaptrude/plugin-core 0.9.12 → 0.9.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.9.12",
+  "version": "0.9.13",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/api/design/family.ts

@@ -253,6 +253,32 @@ export abstract class PluginDesignFamilyApi {
   public abstract create(
     args?: PluginDesignFamilyCreateArgs,
   ): PluginApiReturn<PluginFamilyCreateResult>
+
+  /**
+   * Remove a family from the library: its catalog row is archived, so it
+   * leaves the Families panel. Placed instances are untouched — in this
+   * project and every other — because archived pins keep resolving. Pass
+   * `instances: true` to ALSO delete this project's instances in one undoable
+   * command; do that only when the user asks for the instances to go.
+   *
+   * Omit `id` to target the prepared draft. `id` may be a draft id, a saved
+   * catalog id, or any family from `list()`.
+   *
+   * @param args Optional family id, and whether to delete instances too
+   * @returns Whether a library row was archived and how many instances were removed
+   *
+   * @examplePrompt Delete the Louvre Screen family from my library
+   * @examplePrompt Get rid of that bollard and every copy of it in here
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.family.delete({ id: "revit:steel-bollard~bef047" })
+   * await snaptrude.design.family.delete({ id: "revit:steel-bollard~bef047", instances: true })
+   * ```
+   */
+  public abstract delete(
+    args?: PluginDesignFamilyDeleteArgs,
+  ): PluginApiReturn<PluginFamilyDeleteResult>
 }
 
 // ---------------------------------------------------------------------------
@@ -439,6 +465,21 @@ export interface PluginFamilyCreateResult {
   definitionId?: string
   version?: number
   guid?: string
+  /** True when the save also dropped one instance into the model (nothing was placed yet). */
+  placed?: boolean
+  /** Host guidance for the caller, e.g. that an instance was placed at the view centre. */
+  hint?: string
+  error?: string
+}
+
+/** What `delete` reports. */
+export interface PluginFamilyDeleteResult {
+  ok: boolean
+  familyId?: string
+  /** Instances deleted from the scene (only with `instances: true`), in one undoable command. */
+  removedInstances?: number
+  /** True when a library row was archived; false for an unsaved draft. */
+  archived?: boolean
   error?: string
 }
 
@@ -536,6 +577,20 @@ export const PluginDesignFamilyCreateArgs = z.object({
 })
 export type PluginDesignFamilyCreateArgs = z.infer<typeof PluginDesignFamilyCreateArgs>
 
+/**
+ * Arguments for {@linkcode PluginDesignFamilyApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Family to remove; omit for the prepared draft |
+ * | `instances` | `boolean` | Also delete this project's placed instances; default false |
+ */
+export const PluginDesignFamilyDeleteArgs = z.object({
+  id: z.string().optional(),
+  instances: z.boolean().optional(),
+})
+export type PluginDesignFamilyDeleteArgs = z.infer<typeof PluginDesignFamilyDeleteArgs>
+
 /**
  * Arguments for {@linkcode PluginDesignFamilyApi.place}.
  *