@snaptrude/plugin-core 0.7.1 → 0.8.0

package/src/api/core/io/export/index.ts

@@ -0,0 +1,124 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+
+/**
+ * Serialization format for {@link PluginCoreIoExportApi.model}.
+ *
+ * `glb` / `obj` serialize in the browser; `fbx` / `3ds` run the same server
+ * conversion the app's Export dialog uses and return a **zip** containing the
+ * converted file.
+ */
+export const ExportModelFormat = z.enum(["glb", "obj", "fbx", "3ds"])
+export type ExportModelFormat = z.infer<typeof ExportModelFormat>
+
+/**
+ * What to export: the whole model (`"scene"`, default) or only the current
+ * selection (`"selection"`).
+ */
+export const ExportScope = z.enum(["scene", "selection"])
+export type ExportScope = z.infer<typeof ExportScope>
+
+/**
+ * A serialized model file returned by {@link PluginCoreIoExportApi.model}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `fileName` | `string` | Suggested file name incl. extension (e.g. `"model.glb"`) |
+ * | `mimeType` | `string` | MIME type (`"model/gltf-binary"` for glb, `"text/plain"` for obj) |
+ * | `dataBase64` | `string` | The file's bytes, base64-encoded (decode to save/download) |
+ */
+export const ExportedFile = z.object({
+  fileName: z.string(),
+  mimeType: z.string(),
+  dataBase64: z.string(),
+})
+export type ExportedFile = z.infer<typeof ExportedFile>
+
+/**
+ * Model export — serialize the scene (or selection) to a downloadable 3D file.
+ *
+ * `core.io.export.model` hands you the file bytes as base64 — no download
+ * dialog opens; the plugin decides what to do with the result (save it, POST
+ * it, diff it). Four formats:
+ *
+ * - `"glb"` — binary glTF (`model/gltf-binary`); geometry + materials,
+ *   serialized in the browser (nothing is uploaded).
+ * - `"obj"` — Wavefront OBJ text (`text/plain`); geometry only, serialized in
+ *   the browser.
+ * - `"fbx"` / `"3ds"` — Autodesk FBX / 3D Studio; the scene is uploaded to the
+ *   same `/exportmodel/` conversion service the app's Export dialog uses, and
+ *   the call resolves once the converted artifact is fetched back — a **zip**
+ *   (`application/zip`) containing the `.fbx`/`.3ds` file. Whole-scene only
+ *   (`scope: "selection"` is rejected). Conversion runs on the server and is
+ *   bounded by the per-call plugin timeout (60 s) — very large models may
+ *   exceed it and reject with `TIMEOUT`.
+ *
+ * For the browser formats, only real model geometry is exported (walls, slabs,
+ * roofs, floors, doors, windows, furniture, staircases, masses, ceilings,
+ * mullions, beams, columns, terrain); UI helpers, hidden objects, and
+ * hidden-bucket objects are excluded — matching the app's GLB export. The
+ * server formats convert the full serialized scene (hidden-bucket objects
+ * excluded), exactly like the Export dialog. This is a **read**: it never
+ * mutates the model.
+ *
+ * > Server-backed BIM exports (RVT / IFC / DWG) are **not** exposed here — those
+ * > run as fire-and-forget Forge jobs that stream a browser download and return
+ * > no retrievable bytes. Use the app's Export menu for those.
+ *
+ * Accessed via `snaptrude.core.io.export`.
+ */
+export abstract class PluginCoreIoExportApi {
+  constructor() {}
+
+  /**
+   * Export the model to a 3D file and return its bytes as base64.
+   *
+   * @param format - `"glb"` (binary glTF, geometry + materials), `"obj"`
+   *   (Wavefront OBJ text, geometry only) — both serialized in the browser —
+   *   or `"fbx"` / `"3ds"`, converted by the app's export service and returned
+   *   as a zip containing the converted file.
+   * @param scope - `"scene"` (default) for the whole model, or `"selection"` for
+   *   only the currently selected objects (browser formats only — `"fbx"`/`"3ds"`
+   *   reject it). An empty selection yields an empty file.
+   * @returns an {@linkcode ExportedFile} — `{ fileName, mimeType, dataBase64 }`.
+   * @throws if the format is unsupported, `scope: "selection"` is combined with a
+   *   server format, or the serialization/conversion fails.
+   *
+   * @examplePrompt Export the model as a GLB
+   * @examplePrompt Give me the whole scene as an OBJ file
+   * @examplePrompt Export just my selection to GLB
+   * @examplePrompt Download the model as an FBX file
+   * @examplePrompt Export the scene to 3DS for 3ds Max
+   *
+   * # Example
+   * ```ts
+   * const file = await snaptrude.core.io.export.model("glb")
+   * // decode base64 → bytes and save/download in the plugin UI
+   * const bytes = Uint8Array.from(atob(file.dataBase64), (c) => c.charCodeAt(0))
+   * const blob = new Blob([bytes], { type: file.mimeType })
+   * // ...offer blob for download as file.fileName
+   *
+   * // Only the current selection, as OBJ text:
+   * const obj = await snaptrude.core.io.export.model("obj", "selection")
+   * const text = atob(obj.dataBase64)
+   * ```
+   */
+  public abstract model(
+    format: ExportModelFormat,
+    scope?: ExportScope,
+  ): PluginApiReturn<ExportedFile>
+}
+
+/**
+ * Arguments for {@link PluginCoreIoExportApi.model}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `format` | {@link ExportModelFormat} | `"glb"`, `"obj"`, `"fbx"`, or `"3ds"` |
+ * | `scope` | {@link ExportScope} | `"scene"` (default) or `"selection"` (browser formats only) |
+ */
+export const PluginExportModelArgs = z.object({
+  format: ExportModelFormat,
+  scope: ExportScope.optional(),
+})
+export type PluginExportModelArgs = z.infer<typeof PluginExportModelArgs>

package/src/api/core/io/index.ts

@@ -3,6 +3,7 @@ import { PluginCoreIoJobApi } from "./job"
 import { PluginCoreIoUnderlayApi } from "./underlay"
 import { PluginCoreIoTerrainApi } from "./terrain"
 import { PluginCoreIoQueryApi } from "./query"
+import { PluginCoreIoExportApi } from "./export"
 
 /**
  * I/O — bring external files into the project and manage what was imported.
@@ -12,6 +13,7 @@ import { PluginCoreIoQueryApi } from "./query"
  * - {@linkcode PluginCoreIoApi.job} — poll long-running async imports (e.g. DWG)
  * - {@linkcode PluginCoreIoApi.underlay} — inspect/scale/opacity/delete placed underlays
  * - {@linkcode PluginCoreIoApi.terrain} — inspect/edit the site terrain (datum, layers, delete)
+ * - {@linkcode PluginCoreIoApi.export} — serialize the model to glb/obj (base64 bytes)
  *
  * Accessed via `snaptrude.core.io`.
  */
@@ -26,6 +28,8 @@ export abstract class PluginCoreIoApi {
   public abstract underlay: PluginCoreIoUnderlayApi
   /** Inspect and manage the site terrain. See {@linkcode PluginCoreIoTerrainApi}. */
   public abstract terrain: PluginCoreIoTerrainApi
+  /** Serialize the model to a downloadable 3D file. See {@linkcode PluginCoreIoExportApi}. */
+  public abstract export: PluginCoreIoExportApi
 
   constructor() {}
 }
@@ -35,3 +39,4 @@ export * from "./job"
 export * from "./underlay"
 export * from "./terrain"
 export * from "./query"
+export * from "./export"

package/src/api/core/proposals/index.ts

@@ -136,30 +136,70 @@ export abstract class PluginCoreProposalsApi {
   public abstract isActive(proposalId: string): PluginApiReturn<boolean>
 
   /**
-   * Create a new design option (proposal).
+   * Create a new design option (proposal) — blank, or configured from a base
+   * proposal (the New Proposal modal's two paths).
    *
    * **Pro-gated** (creating proposals requires a Pro plan, matching the UI) and
-   * **not undoable**. Creates a bare proposal with a single empty default
-   * bucket — it does **not** carry forward the current proposal's layers, views,
-   * or targets. The name is capped at 24 characters.
+   * **not undoable**. The name is capped at 24 characters.
+   *
+   * **Blank** (no `options`) — creates a bare proposal with a single empty
+   * default bucket; it does **not** carry forward the current proposal's
+   * layers, views, or targets, and the active proposal does **not** change.
+   *
+   * **Configured** (`options.baseProposalId`) — the modal's Configure path:
+   * carries the base proposal's buckets (layers) forward per `options.layers`,
+   * where each entry names a bucket of the base proposal and an action —
+   * `"share"` (the new proposal references the same live bucket) or
+   * `"duplicate"` (an independent copy of the bucket and its contents).
+   * Buckets not listed are left behind. Omitting `layers` carries **every**
+   * base bucket forward as a `"duplicate"` (the modal's default). The base
+   * proposal's views and area targets are copied either way, and the new
+   * proposal becomes the **active** one (implicit switch — blocked with
+   * `PROPOSAL_SWITCH_BLOCKED` while an in-canvas agent run is in flight, like
+   * {@linkcode PluginCoreProposalsApi.setActive}).
    *
    * @param name - Display name of the new proposal (capped at 24 chars).
+   * @param options - Optional configure path: `baseProposalId` (the proposal to
+   *   carry forward from) and `layers` (per-bucket `"share"` / `"duplicate"`
+   *   actions; omitted buckets are excluded, omitted `layers` duplicates all).
    * @returns The new proposal's id (read the full record back with
    *   {@linkcode PluginCoreProposalsApi.get}).
-   * @throws If the caller is not on a Pro plan, or the proposal could not be
-   *   created.
+   * @throws If the caller is not on a Pro plan, the name is empty/duplicate,
+   *   `layers` is passed without `baseProposalId`, the base proposal or a
+   *   listed bucket does not exist / does not belong to the base proposal, or
+   *   (configured only) `PROPOSAL_SWITCH_BLOCKED` while a canvas-agent run is
+   *   in flight.
    *
    * @examplePrompt Create a design option called Scheme B
    * @examplePrompt Add a new proposal named Option 2
-   * @examplePrompt Make a fresh design variant to explore
+   * @examplePrompt Duplicate the current proposal as Scheme C
+   * @examplePrompt Create a design option based on Proposal 1 that shares its site layer
    *
    * # Example
    * ```ts
+   * // blank design option
    * const { id } = await snaptrude.core.proposals.create("Scheme B")
+   *
+   * // configured from the active proposal: duplicate every layer
+   * const base = await snaptrude.core.proposals.getActive()
+   * if (base) {
+   *   const { id: dup } = await snaptrude.core.proposals.create("Scheme C", {
+   *     baseProposalId: base.id,
+   *   })
+   *   // …or share one layer and leave the rest behind
+   *   const { id: shared } = await snaptrude.core.proposals.create("Scheme D", {
+   *     baseProposalId: base.id,
+   *     layers: [{ bucketId: base.defaultBucketId, action: "share" }],
+   *   })
+   * }
    * ```
    */
   public abstract create(
     name: string,
+    options?: {
+      baseProposalId: string
+      layers?: { bucketId: string; action: "share" | "duplicate" }[]
+    },
   ): PluginApiReturn<PluginCoreProposalsCreateResult>
 
   /**
@@ -383,15 +423,35 @@ export type PluginCoreProposalsIsActiveArgs = z.infer<
 >
 
 /**
- * Arguments for {@linkcode PluginCoreProposalsApi.create}.
+ * Arguments for {@linkcode PluginCoreProposalsApi.create}. A bare `name` makes
+ * a blank proposal; `baseProposalId` switches to the configured (carry-forward)
+ * path. `layers` requires `baseProposalId` — each entry names a bucket of the
+ * base proposal; omitted buckets are excluded, and omitting `layers` entirely
+ * duplicates every base bucket.
  *
  * | Property | Type | Description |
  * |---|---|---|
  * | `name` | `string` | Display name of the new proposal (capped at 24 chars) |
+ * | `baseProposalId` | `string \| undefined` | Proposal to carry forward from (configured path) |
+ * | `layers` | `{ bucketId: string; action: "share" \| "duplicate" }[] \| undefined` | Per-bucket carry-forward actions (requires `baseProposalId`) |
  */
-export const PluginCoreProposalsCreateArgs = z.object({
-  name: z.string(),
-})
+export const PluginCoreProposalsCreateArgs = z
+  .object({
+    name: z.string(),
+    baseProposalId: z.string().optional(),
+    layers: z
+      .array(
+        z.object({
+          bucketId: z.string(),
+          action: z.enum(["share", "duplicate"]),
+        }),
+      )
+      .optional(),
+  })
+  .refine((v) => v.layers === undefined || v.baseProposalId !== undefined, {
+    message:
+      "layers requires baseProposalId — the layers describe how to carry the base proposal's buckets forward",
+  })
 export type PluginCoreProposalsCreateArgs = z.infer<
   typeof PluginCoreProposalsCreateArgs
 >

package/src/api/core/user.ts

@@ -0,0 +1,46 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * User locale.
+ *
+ * Read the viewer's timezone and language — for date/number formatting and
+ * localized labels. This is locale only: NO precise geolocation, no IP, no
+ * account identity. Accessed via `snaptrude.core.user`.
+ */
+export abstract class PluginUserApi {
+  constructor() {}
+
+  /**
+   * Get the viewer's locale: IANA timezone and BCP-47 language tag, resolved
+   * from the browser (`Intl.DateTimeFormat().resolvedOptions().timeZone` and
+   * `navigator.language`). Locale only — no precise location.
+   *
+   * @returns `{ timezone, language }` — e.g. `{ timezone: "Asia/Kolkata", language: "en-US" }`.
+   *
+   * @examplePrompt What timezone is the user in?
+   * @examplePrompt Get the viewer's language for localized labels
+   * @examplePrompt Format the report date in the user's local timezone
+   * @examplePrompt Which locale should I use for this plugin's UI?
+   *
+   * # Example
+   * ```ts
+   * const { timezone, language } = await snaptrude.core.user.getLocale()
+   * ```
+   */
+  public abstract getLocale(): PluginApiReturn<PluginUserLocale>
+}
+
+/**
+ * The viewer's locale.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `timezone` | `string` | IANA timezone id (e.g. `"Asia/Kolkata"`) |
+ * | `language` | `string` | BCP-47 language tag (e.g. `"en-US"`) |
+ */
+export const PluginUserLocale = z.object({
+  timezone: z.string(),
+  language: z.string(),
+})
+export type PluginUserLocale = z.infer<typeof PluginUserLocale>