@snaptrude/plugin-core 0.9.16 → 0.9.18-edgesetbacks-20261021.1

package/src/api/design/types/index.ts

@@ -1,156 +1,163 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-
-/**
- * `snaptrude.design.types` — READ-ONLY reference over the project's building
- * **type / assembly** system (the Project Properties layer stacks: External /
- * Internal walls, slabs, floors, ceilings, roofs). A type bundles a labelled
- * layer stack — each layer's role, thickness (engine units) and material — plus a
- * summed total thickness. Both the built-in defaults and any team/user-added types
- * are surfaced.
- *
- * Types are plain value records ({@linkcode PluginBuildingType}) — NOT scene
- * entities/handles. A type's `id` is a stable `"<kind>:<name>"` token
- * (e.g. `"wall:brickWithPlasterAndPaint"`) returned by
- * {@linkcode PluginDesignTypesApi.list} and consumed by
- * {@linkcode PluginDesignTypesApi.get}. Reads never throw — an unknown id yields
- * `null`; a kind with no types yields `[]`.
- *
- * These are reads only: there is no engine seam to author a type from a plugin
- * (types are created through the construction/project-properties UI).
- */
-export abstract class PluginDesignTypesApi {
-  constructor() {}
-
-  /**
-   * List the building types of one `kind` (wall / slab / floor / ceiling / roof)
-   * — the built-in defaults plus any team/user-added types. Returns lightweight
-   * summaries; call {@linkcode PluginDesignTypesApi.get} for the full layer stack.
-   *
-   * @param kind Which family of types to list
-   * @returns The type summaries as {@linkcode PluginBuildingTypeSummary}`[]` (`[]` when none)
-   *
-   * @examplePrompt What wall types does this project have?
-   * @examplePrompt List the available slab assemblies
-   * @examplePrompt Show me every roof type in the project
-   * @examplePrompt Which floor types can I use?
-   *
-   * # Example
-   * ```ts
-   * const wallTypes = await snaptrude.design.types.list("wall")
-   * for (const t of wallTypes) console.log(t.id, t.label, t.thickness)
-   * ```
-   */
-  public abstract list(
-    kind: PluginBuildingTypeKind
-  ): PluginApiReturn<PluginBuildingTypeSummary[]>
-
-  /**
-   * Get one building type by its `"<kind>:<name>"` id — its labelled layer stack
-   * (each layer's role, thickness and material) plus the summed total thickness.
-   *
-   * @param typeId The type id from {@linkcode PluginDesignTypesApi.list} (e.g. `"wall:exposedConcrete"`)
-   * @returns The full type, or `null` if no type matches
-   *
-   * @examplePrompt What layers make up this wall type?
-   * @examplePrompt Show the construction of the exposed-concrete wall
-   * @examplePrompt What's the total thickness of this slab type?
-   * @examplePrompt Which materials are in this roof assembly?
-   *
-   * # Example
-   * ```ts
-   * const [first] = await snaptrude.design.types.list("wall")
-   * const type = await snaptrude.design.types.get(first.id)
-   * if (type) for (const layer of type.layers) console.log(layer.name, layer.thickness)
-   * ```
-   */
-  public abstract get(typeId: string): PluginApiReturn<PluginBuildingType | null>
-}
-
-/** The building-type families exposed by {@linkcode PluginDesignTypesApi}. */
-export const PluginBuildingTypeKind = z.enum(["wall", "slab", "floor", "ceiling", "roof"])
-export type PluginBuildingTypeKind = z.infer<typeof PluginBuildingTypeKind>
-
-/**
- * One layer of a building type's assembly.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `name` | `string` | Layer name (e.g. `"RCC"`, `"Paint"`) |
- * | `role` | `string` | Layer role (e.g. `"Structure"`, `"Finish"`) |
- * | `thickness` | `number` | Layer thickness in engine units (project's active unit mode) |
- * | `material` | `object`? | Layer material — `{ name, type }` (optional) |
- */
-export const PluginTypeLayer = z.object({
-  name: z.string(),
-  role: z.string(),
-  thickness: z.number(),
-  material: z
-    .object({
-      name: z.string(),
-      type: z.string(),
-    })
-    .optional(),
-})
-export type PluginTypeLayer = z.infer<typeof PluginTypeLayer>
-
-/**
- * A lightweight building-type summary (no layer stack).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | Stable `"<kind>:<name>"` token — pass to `design.types.get` |
- * | `kind` | {@linkcode PluginBuildingTypeKind} | Which family it belongs to |
- * | `label` | `string` | Human-readable label |
- * | `isDefault` | `boolean` | `true` for a built-in type, `false` for a team/user type |
- * | `thickness` | `number` | Summed layer thickness in engine units |
- */
-export const PluginBuildingTypeSummary = z.object({
-  id: z.string(),
-  kind: PluginBuildingTypeKind,
-  label: z.string(),
-  isDefault: z.boolean(),
-  thickness: z.number(),
-})
-export type PluginBuildingTypeSummary = z.infer<typeof PluginBuildingTypeSummary>
-
-/**
- * A full building type — a {@linkcode PluginBuildingTypeSummary} plus its layer stack.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | Stable `"<kind>:<name>"` token |
- * | `kind` | {@linkcode PluginBuildingTypeKind} | Which family it belongs to |
- * | `label` | `string` | Human-readable label |
- * | `isDefault` | `boolean` | `true` for a built-in type |
- * | `thickness` | `number` | Summed layer thickness in engine units |
- * | `layers` | {@linkcode PluginTypeLayer}`[]` | The ordered layer stack |
- */
-export const PluginBuildingType = PluginBuildingTypeSummary.extend({
-  layers: z.array(PluginTypeLayer),
-})
-export type PluginBuildingType = z.infer<typeof PluginBuildingType>
-
-/**
- * Arguments for {@linkcode PluginDesignTypesApi.list}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `kind` | {@linkcode PluginBuildingTypeKind} | Which family of types to list |
- */
-export const PluginDesignTypesListArgs = z.object({
-  kind: PluginBuildingTypeKind,
-})
-export type PluginDesignTypesListArgs = z.infer<typeof PluginDesignTypesListArgs>
-
-/**
- * Arguments for {@linkcode PluginDesignTypesApi.get}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `typeId` | `string` | The `"<kind>:<name>"` id from `design.types.list` |
- */
-export const PluginDesignTypesGetArgs = z.object({
-  typeId: z.string(),
-})
-export type PluginDesignTypesGetArgs = z.infer<typeof PluginDesignTypesGetArgs>
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+
+/** An exact saved native wall family. Access is checked on every use; Draw selection is not registration. */
+export const PluginNativeWallType = z.object({
+  id: z.string().min(1),
+  version: z.number().int().positive(),
+})
+export type PluginNativeWallType = z.infer<typeof PluginNativeWallType>
+
+/** Legacy project type name/id, or an exact authorized native wall family pin. */
+export const PluginWallType = z.union([z.string().trim().min(1), PluginNativeWallType])
+export type PluginWallType = z.infer<typeof PluginWallType>
+
+/**
+ * Read-only project assemblies and authorized saved native wall families.
+ * Legacy ids use `"<kind>:<name>"`. Native wall records carry `nativeFamily`:
+ * pass that exact `{ id, version }` pin to get, create.walls, create.wallRuns,
+ * or update.wall. Labels and bare definition ids do not select native families.
+ * Native lengths use Snaptrude units (1 SU = 254 mm).
+ * Missing ids return null; catalog/network failures reject rather than return
+ * an incomplete catalog. Author native families with design.family.
+ */
+export abstract class PluginDesignTypesApi {
+  constructor() {}
+
+  /**
+   * List the building types of one `kind` (wall / slab / floor / ceiling / roof)
+   * — the built-in defaults plus any team/user-added types. Returns lightweight
+   * summaries; call {@linkcode PluginDesignTypesApi.get} for the full layer stack.
+   *
+   * @param kind Which family of types to list
+   * @returns The type summaries as {@linkcode PluginBuildingTypeSummary}`[]` (`[]` when none)
+   *
+   * @examplePrompt What wall types does this project have?
+   * @examplePrompt List the available slab assemblies
+   * @examplePrompt Show me every roof type in the project
+   * @examplePrompt Which floor types can I use?
+   *
+   * # Example
+   * ```ts
+   * const wallTypes = await snaptrude.design.types.list("wall")
+   * for (const t of wallTypes) console.log(t.id, t.label, t.thickness)
+   * ```
+   */
+  public abstract list(
+    kind: PluginBuildingTypeKind
+  ): PluginApiReturn<PluginBuildingTypeSummary[]>
+
+  /**
+   * Get one building type by its legacy id or exact native wall pin — its labelled layer stack
+   * (each layer's role, thickness and material) plus the summed total thickness.
+   *
+   * @param typeId The legacy id or nativeFamily pin from {@linkcode PluginDesignTypesApi.list}
+   * @returns The full type, or `null` if no type matches
+   *
+   * @examplePrompt What layers make up this wall type?
+   * @examplePrompt Show the construction of the exposed-concrete wall
+   * @examplePrompt What's the total thickness of this slab type?
+   * @examplePrompt Which materials are in this roof assembly?
+   *
+   * # Example
+   * ```ts
+   * const [first] = await snaptrude.design.types.list("wall")
+   * const type = await snaptrude.design.types.get(first.nativeFamily ?? first.id)
+   * if (type) for (const layer of type.layers) console.log(layer.name, layer.thickness)
+   * ```
+   */
+  public abstract get(typeId: PluginWallType): PluginApiReturn<PluginBuildingType | null>
+}
+
+/** The building-type families exposed by {@linkcode PluginDesignTypesApi}. */
+export const PluginBuildingTypeKind = z.enum(["wall", "slab", "floor", "ceiling", "roof"])
+export type PluginBuildingTypeKind = z.infer<typeof PluginBuildingTypeKind>
+
+/**
+ * One layer of a building type's assembly.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Layer name (e.g. `"RCC"`, `"Paint"`) |
+ * | `role` | `string` | Layer role (e.g. `"Structure"`, `"Finish"`) |
+ * | `thickness` | `number` | Layer thickness in engine units (project's active unit mode) |
+ * | `material` | `object`? | Layer material — `{ name, type }` (optional) |
+ */
+export const PluginTypeLayer = z.object({
+  name: z.string(),
+  role: z.string(),
+  thickness: z.number(),
+  /** Native authored core membership. Never inferred from material or layer name. */
+  isCore: z.boolean().optional(),
+  material: z
+    .object({
+      name: z.string(),
+      type: z.string(),
+    })
+    .optional(),
+})
+export type PluginTypeLayer = z.infer<typeof PluginTypeLayer>
+
+/**
+ * A lightweight building-type summary (no layer stack).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Legacy `"<kind>:<name>"` token or native definition id; native lookups use `nativeFamily` |
+ * | `kind` | {@linkcode PluginBuildingTypeKind} | Which family it belongs to |
+ * | `label` | `string` | Human-readable label |
+ * | `isDefault` | `boolean` | `true` for a built-in type, `false` for a team/user type |
+ * | `thickness` | `number` | Summed layer thickness in engine units |
+ */
+export const PluginBuildingTypeSummary = z.object({
+  id: z.string(),
+  kind: PluginBuildingTypeKind,
+  label: z.string(),
+  isDefault: z.boolean(),
+  thickness: z.number(),
+  /** Present for native walls. Pass the whole pin to get/create/update, not its label or bare id. */
+  nativeFamily: PluginNativeWallType.optional(),
+})
+export type PluginBuildingTypeSummary = z.infer<typeof PluginBuildingTypeSummary>
+
+/**
+ * A full building type — a {@linkcode PluginBuildingTypeSummary} plus its layer stack.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Legacy type token or native definition id |
+ * | `kind` | {@linkcode PluginBuildingTypeKind} | Which family it belongs to |
+ * | `label` | `string` | Human-readable label |
+ * | `isDefault` | `boolean` | `true` for a built-in type |
+ * | `thickness` | `number` | Summed layer thickness in engine units |
+ * | `layers` | {@linkcode PluginTypeLayer}`[]` | The ordered layer stack |
+ */
+export const PluginBuildingType = PluginBuildingTypeSummary.extend({
+  layers: z.array(PluginTypeLayer),
+})
+export type PluginBuildingType = z.infer<typeof PluginBuildingType>
+
+/**
+ * Arguments for {@linkcode PluginDesignTypesApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `kind` | {@linkcode PluginBuildingTypeKind} | Which family of types to list |
+ */
+export const PluginDesignTypesListArgs = z.object({
+  kind: PluginBuildingTypeKind,
+})
+export type PluginDesignTypesListArgs = z.infer<typeof PluginDesignTypesListArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignTypesApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `typeId` | {@linkcode PluginWallType} | A legacy `"<kind>:<name>"` id or exact `nativeFamily` pin from `design.types.list` |
+ */
+export const PluginDesignTypesGetArgs = z.object({
+  // Preserve legacy lookup behavior: malformed string ids return null in the host.
+  typeId: z.union([z.string(), PluginNativeWallType]),
+})
+export type PluginDesignTypesGetArgs = z.infer<typeof PluginDesignTypesGetArgs>