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

package/src/api/design/catalog.ts

@@ -0,0 +1,203 @@
+import * as z from "zod"
+import { ContourHandle, LineHandle, Vec3Handle } from "../../handles"
+import type { PluginApiReturn } from "../../types"
+import {
+  PluginFamilyDefinitionParameter,
+  PluginFamilyBundleSchema,
+} from "./family"
+import { NetworkFamilyContract } from "./networks"
+
+/** Exact saved family identity. A label or a selected Draw type is not an identity. */
+export const PluginSavedFamilyReference = z
+  .object({
+    id: z.string().min(1),
+    version: z.number().int().positive(),
+  })
+  .strict()
+export type PluginSavedFamilyReference = z.infer<
+  typeof PluginSavedFamilyReference
+>
+
+/** Public overrides: physical lengths use mm, angles use degrees. Omitted values retain defaults. */
+export const PluginFamilyValues = z.record(
+  z.string(),
+  z.union([z.number().finite(), z.string(), z.boolean()]),
+)
+export type PluginFamilyValues = z.infer<typeof PluginFamilyValues>
+
+/** Native construction uses a saved family or a project assembly token from the catalogue. */
+export const PluginConstructionType = z.union([
+  PluginSavedFamilyReference,
+  z.string().min(1),
+])
+export type PluginConstructionType = z.infer<typeof PluginConstructionType>
+
+/** Family owns its layers/section. Geometry owns the footprint/axis; it is never a values override. */
+export const PluginFamilyPlacement = z
+  .object({
+    type: PluginConstructionType,
+    values: PluginFamilyValues.optional(),
+  })
+  .strict()
+export type PluginFamilyPlacement = z.infer<typeof PluginFamilyPlacement>
+
+/** Sparse native family edit. Omitted type keeps the component's exact saved reference. */
+export const PluginFamilyUpdates = PluginFamilyPlacement.partial().refine(
+  (updates) => updates.type !== undefined || updates.values !== undefined,
+  { message: "Supply a type or parameter values" },
+)
+export type PluginFamilyUpdates = z.infer<typeof PluginFamilyUpdates>
+
+export const PluginFamilyFloorOptions = PluginFamilyPlacement.extend({
+  position: Vec3Handle.optional(),
+})
+export type PluginFamilyFloorOptions = z.infer<typeof PluginFamilyFloorOptions>
+export const PluginFamilySlabOptions = PluginFamilyPlacement.extend({
+  direction: z.enum(["up", "down"]).optional(),
+})
+export type PluginFamilySlabOptions = z.infer<typeof PluginFamilySlabOptions>
+export const PluginFamilyCeilingOptions = PluginFamilyPlacement.extend({
+  heightFromFloor: z.number().finite().optional(),
+})
+export type PluginFamilyCeilingOptions = z.infer<
+  typeof PluginFamilyCeilingOptions
+>
+export const PluginFamilyContourArgs = z.object({
+  contour: ContourHandle,
+  options: PluginFamilyPlacement,
+})
+export const PluginFamilyAxisArgs = z.object({
+  axis: LineHandle,
+  options: PluginFamilyPlacement,
+})
+
+/** Inventory includes architectural recipes, ordinary PCs, and the existing placement libraries. */
+export const PluginCatalogKind = z.enum([
+  "wall",
+  "floor",
+  "slab",
+  "roof",
+  "ceiling",
+  "beam",
+  "column",
+  "component",
+  "door",
+  "window",
+  "furniture",
+])
+export type PluginCatalogKind = z.infer<typeof PluginCatalogKind>
+export const PluginCatalogReference = z.union([
+  PluginSavedFamilyReference,
+  // Project assemblies retain kind:name; asset tokens retain the underlying library identity.
+  z.string().min(1),
+])
+export type PluginCatalogReference = z.infer<typeof PluginCatalogReference>
+
+/** Read-only capability record. Availability is checked again on every mutation. */
+export const PluginCatalogEntry = z.object({
+  reference: PluginCatalogReference,
+  label: z.string(),
+  kind: PluginCatalogKind,
+  source: z.enum(["native", "revit", "project", "asset"]),
+  createMethods: z.array(z.string()),
+  updateMethods: z.array(z.string()),
+  requirements: z.array(z.string()),
+  unsupportedReason: z.string().optional(),
+  parameters: z.array(PluginFamilyDefinitionParameter).optional(),
+  /** Parameter keys owned by native placement geometry, never accepted as values overrides. */
+  geometryParameters: z.array(z.string()),
+  network: NetworkFamilyContract.optional(),
+  /** get() includes the native wall recipe without opening a Family Studio draft.
+   * Bare recipe lengths use SU; parameter metadata and public values overrides use mm.
+   */
+  construction: PluginFamilyBundleSchema.optional(),
+})
+export type PluginCatalogEntry = z.infer<typeof PluginCatalogEntry>
+export const PluginCatalogListArgs = z.object({
+  kind: PluginCatalogKind.optional(),
+})
+export const PluginCatalogGetArgs = z.object({
+  reference: PluginCatalogReference,
+})
+
+/** Search metadata is extensible. A slash separates category path segments. */
+export const PluginCatalogSearchArgs = z
+  .object({
+    query: z.string().trim().max(200).optional(),
+    category: z.string().trim().max(1000).optional(),
+    limit: z.number().int().min(1).max(50).optional(),
+    cursor: z.string().min(1).max(16384).optional(),
+  })
+  .strict()
+export type PluginCatalogSearchArgs = z.infer<typeof PluginCatalogSearchArgs>
+
+/** Browse one hierarchy level without enumerating families or fetching recipe bodies. */
+export const PluginCatalogListCategoriesArgs = z
+  .object({
+    parent: z.string().trim().max(1000).optional(),
+    after: z.string().max(1000).optional(),
+    limit: z.number().int().min(1).max(100).optional(),
+  })
+  .strict()
+export type PluginCatalogListCategoriesArgs = z.infer<
+  typeof PluginCatalogListCategoriesArgs
+>
+
+/** Metadata only: the category does not establish placement capabilities or recipe validity. */
+export const PluginCatalogCategory = z.object({
+  categoryPath: z.array(z.string()).min(1),
+  hasChildren: z.boolean(),
+})
+export type PluginCatalogCategory = z.infer<typeof PluginCatalogCategory>
+
+/** Metadata only. Read get(reference) to validate a selected family and inspect placement methods. */
+export const PluginCatalogSummary = z.object({
+  reference: PluginCatalogReference,
+  label: z.string(),
+  categoryPath: z.array(z.string()),
+  description: z.string(),
+  source: PluginCatalogEntry.shape.source,
+})
+export type PluginCatalogSummary = z.infer<typeof PluginCatalogSummary>
+export const PluginCatalogSearchResult = z.object({
+  items: z.array(PluginCatalogSummary),
+  nextCursor: z.string().nullable(),
+})
+export type PluginCatalogSearchResult = z.infer<
+  typeof PluginCatalogSearchResult
+>
+
+/** Shared read surface over existing libraries. Does not publish, register, or place definitions. */
+export abstract class PluginDesignCatalogApi {
+  /**
+   * Discover categories from accessible saved families and current project constructions.
+   * Omit parent for roots; pass a slash-separated returned path for its direct children.
+   * This metadata read does not fetch recipes, include unsaved drafts or legacy mesh inventories,
+   * or establish capabilities. Use search then get before placement. Names retain their case.
+   * @param args Parent path, exclusive after-name, and page limit (default 50, maximum 100).
+   * For another page at the same parent, pass the last item's final categoryPath segment as after.
+   * @returns Categories in Unicode code-point order, with descendant flags. Stop when a page has
+   * fewer than limit items. Live pagination is not a snapshot. Metadata-service failures reject.
+   */
+  abstract listCategories(
+    args?: PluginCatalogListCategoriesArgs,
+  ): PluginApiReturn<PluginCatalogCategory[]>
+  /**
+   * Search accessible saved-family and project-construction metadata without downloading recipes.
+   * Categories are data, not an SDK enum. Legacy mesh inventories and unsaved drafts are excluded.
+   * Inspect selected references with get before placement; a search match does not prove validity
+   * or supported behavior. Pagination reads live data, not a snapshot. Failures reject.
+   * @param args Text/category filters, page limit (default 20, maximum 50), and opaque cursor.
+   * @returns Compact metadata and continuation. Continue until nextCursor is null or a suitable
+   * family is found. Concurrent changes can leave an empty page with continuation.
+   */
+  abstract search(
+    args?: PluginCatalogSearchArgs,
+  ): PluginApiReturn<PluginCatalogSearchResult>
+  /** @param kind Optional element filter. @returns Accessible entries and their supported API paths. */
+  abstract list(kind?: PluginCatalogKind): PluginApiReturn<PluginCatalogEntry[]>
+  /** @param reference Exact reference from search or list. @returns The current entry, or null when unavailable. */
+  abstract get(
+    reference: PluginCatalogReference,
+  ): PluginApiReturn<PluginCatalogEntry | null>
+}