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

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

@@ -1,42 +1,42 @@
-import { PluginCoreIoImportApi } from "./import"
-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.
- *
- * - {@linkcode PluginCoreIoApi.import} — import images, PDFs, CAD, 3D models, terrain
- * - {@linkcode PluginCoreIoApi.query} — read source metadata before importing (pdf pages, cad layers)
- * - {@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`.
- */
-export abstract class PluginCoreIoApi {
-  /** Import external files into the scene. See {@linkcode PluginCoreIoImportApi}. */
-  public abstract import: PluginCoreIoImportApi
-  /** Read source metadata before import. See {@linkcode PluginCoreIoQueryApi}. */
-  public abstract query: PluginCoreIoQueryApi
-  /** Poll long-running import jobs. See {@linkcode PluginCoreIoJobApi}. */
-  public abstract job: PluginCoreIoJobApi
-  /** Inspect and edit placed underlays. See {@linkcode PluginCoreIoUnderlayApi}. */
-  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() {}
-}
-
-export * from "./import"
-export * from "./job"
-export * from "./underlay"
-export * from "./terrain"
-export * from "./query"
-export * from "./export"
+import { PluginCoreIoImportApi } from "./import"
+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.
+ *
+ * - {@linkcode PluginCoreIoApi.import} — import images, PDFs, CAD, 3D models, terrain
+ * - {@linkcode PluginCoreIoApi.query} — read source metadata before importing (pdf pages, cad layers)
+ * - {@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`.
+ */
+export abstract class PluginCoreIoApi {
+  /** Import external files into the scene. See {@linkcode PluginCoreIoImportApi}. */
+  public abstract import: PluginCoreIoImportApi
+  /** Read source metadata before import. See {@linkcode PluginCoreIoQueryApi}. */
+  public abstract query: PluginCoreIoQueryApi
+  /** Poll long-running import jobs. See {@linkcode PluginCoreIoJobApi}. */
+  public abstract job: PluginCoreIoJobApi
+  /** Inspect and edit placed underlays. See {@linkcode PluginCoreIoUnderlayApi}. */
+  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() {}
+}
+
+export * from "./import"
+export * from "./job"
+export * from "./underlay"
+export * from "./terrain"
+export * from "./query"
+export * from "./export"

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

@@ -1,140 +1,140 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../../types"
-import { ImportJobHandle, UnderlayHandle } from "../../../../handles"
-
-/**
- * Import jobs — poll a long-running asynchronous import.
- *
- * Some imports run on a server and take a while (today: `core.io.import.dwg`,
- * whose DWG → Snaptrude conversion can take minutes). Those importers return an
- * {@linkcode ImportJobHandle} immediately instead of blocking; you drive the job
- * to completion here:
- *
- * 1. poll {@link PluginCoreIoJobApi.isComplete} (or read {@link PluginCoreIoJobApi.getStatus}),
- * 2. once complete, call {@link PluginCoreIoJobApi.getResult} for the placed handle,
- * 3. or read {@link PluginCoreIoJobApi.getError} if it failed.
- *
- * **Always poll with a timeout.** If the import is cancelled from the app UI
- * (or the tab reloads mid-conversion), the job never reaches a terminal state
- * and `getStatus` keeps returning `"processing"` — an unbounded poll loop would
- * spin forever. Give up after a few minutes and surface that to the user.
- *
- * Accessed via `snaptrude.core.io.job`.
- */
-export abstract class PluginCoreIoJobApi {
-  constructor() {}
-
-  /**
-   * Read a job's current status: `"pending"` (queued), `"processing"` (running),
-   * `"complete"` (result ready), or `"failed"`.
-   *
-   * Limitation: a job cancelled from the app UI never turns `"failed"` — it
-   * stays `"processing"` indefinitely. Bound your poll loop with a timeout.
-   *
-   * @param job - The import job to inspect.
-   * @returns the {@linkcode ImportJobStatus}.
-   * @throws {@link HandleInvalidError} if the job handle is unknown.
-   *
-   * @examplePrompt What's the status of my DWG import?
-   * @examplePrompt Is the CAD import still processing?
-   * @examplePrompt Check where the import job is up to
-   * @examplePrompt Did the import job fail?
-   *
-   * # Example
-   * ```ts
-   * const job = await snaptrude.core.io.import.dwg(url, 1)
-   * console.log(await snaptrude.core.io.job.getStatus(job)) // "processing"
-   * ```
-   */
-  public abstract getStatus(job: ImportJobHandle): PluginApiReturn<ImportJobStatus>
-
-  /**
-   * Whether the job has finished successfully (status is `"complete"` and a
-   * result is ready). Returns `false` while pending/processing and on failure.
-   *
-   * @param job - The import job to inspect.
-   * @throws {@link HandleInvalidError} if the job handle is unknown.
-   *
-   * @examplePrompt Is the DWG import done yet?
-   * @examplePrompt Has the CAD import finished?
-   * @examplePrompt Tell me when the import job completes
-   * @examplePrompt Is my import ready?
-   *
-   * # Example
-   * ```ts
-   * const job = await snaptrude.core.io.import.dwg(url, 1)
-   * const deadline = Date.now() + 5 * 60_000 // cap the poll — see getStatus limitation
-   * while (!(await snaptrude.core.io.job.isComplete(job))) {
-   *   if (Date.now() > deadline) throw new Error("DWG import timed out")
-   *   await new Promise((r) => setTimeout(r, 2000))
-   * }
-   * ```
-   */
-  public abstract isComplete(job: ImportJobHandle): PluginApiReturn<boolean>
-
-  /**
-   * The imported result once the job is complete — the placed
-   * {@linkcode UnderlayHandle}. Returns `null` while the job is still
-   * pending/processing or if it failed (check {@link PluginCoreIoJobApi.getError}).
-   *
-   * @param job - The completed import job.
-   * @throws {@link HandleInvalidError} if the job handle is unknown.
-   *
-   * @examplePrompt Get the underlay from my finished DWG import
-   * @examplePrompt Give me the result of the CAD import job
-   * @examplePrompt Fetch the imported CAD sketch once it's ready
-   * @examplePrompt Return the handle for the completed import
-   *
-   * # Example
-   * ```ts
-   * const job = await snaptrude.core.io.import.dwg(url, 1)
-   * const deadline = Date.now() + 5 * 60_000
-   * while (!(await snaptrude.core.io.job.isComplete(job))) {
-   *   if (Date.now() > deadline) throw new Error("DWG import timed out")
-   *   await new Promise((r) => setTimeout(r, 2000))
-   * }
-   * // DWG results are CAD underlays (CAD scaling isn't supported); manage them
-   * // via core.io.underlay.* (list / setOpacity / delete).
-   * const cad = await snaptrude.core.io.job.getResult(job)
-   * if (cad) console.log("import complete:", cad)
-   * ```
-   */
-  public abstract getResult(job: ImportJobHandle): PluginApiReturn<UnderlayHandle | null>
-
-  /**
-   * The failure message if the job's status is `"failed"`; otherwise `null`.
-   *
-   * @param job - The import job to inspect.
-   * @throws {@link HandleInvalidError} if the job handle is unknown.
-   *
-   * @examplePrompt Why did my DWG import fail?
-   * @examplePrompt What went wrong with the CAD import?
-   * @examplePrompt Show the error from the failed import job
-   * @examplePrompt Did the import error out, and why?
-   *
-   * # Example
-   * ```ts
-   * const job = await snaptrude.core.io.import.dwg(url, 1)
-   * if ((await snaptrude.core.io.job.getStatus(job)) === "failed") {
-   *   console.error(await snaptrude.core.io.job.getError(job))
-   * }
-   * ```
-   */
-  public abstract getError(job: ImportJobHandle): PluginApiReturn<string | null>
-}
-
-/** Lifecycle status of an asynchronous import job. */
-export const ImportJobStatus = z.enum(["pending", "processing", "complete", "failed"])
-export type ImportJobStatus = z.infer<typeof ImportJobStatus>
-
-/**
- * Arguments for the `core.io.job.*` readers.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `job` | {@link ImportJobHandle} | The import job to inspect |
- */
-export const PluginImportJobArgs = z.object({
-  job: ImportJobHandle,
-})
-export type PluginImportJobArgs = z.infer<typeof PluginImportJobArgs>
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import { ImportJobHandle, UnderlayHandle } from "../../../../handles"
+
+/**
+ * Import jobs — poll a long-running asynchronous import.
+ *
+ * Some imports run on a server and take a while (today: `core.io.import.dwg`,
+ * whose DWG → Snaptrude conversion can take minutes). Those importers return an
+ * {@linkcode ImportJobHandle} immediately instead of blocking; you drive the job
+ * to completion here:
+ *
+ * 1. poll {@link PluginCoreIoJobApi.isComplete} (or read {@link PluginCoreIoJobApi.getStatus}),
+ * 2. once complete, call {@link PluginCoreIoJobApi.getResult} for the placed handle,
+ * 3. or read {@link PluginCoreIoJobApi.getError} if it failed.
+ *
+ * **Always poll with a timeout.** If the import is cancelled from the app UI
+ * (or the tab reloads mid-conversion), the job never reaches a terminal state
+ * and `getStatus` keeps returning `"processing"` — an unbounded poll loop would
+ * spin forever. Give up after a few minutes and surface that to the user.
+ *
+ * Accessed via `snaptrude.core.io.job`.
+ */
+export abstract class PluginCoreIoJobApi {
+  constructor() {}
+
+  /**
+   * Read a job's current status: `"pending"` (queued), `"processing"` (running),
+   * `"complete"` (result ready), or `"failed"`.
+   *
+   * Limitation: a job cancelled from the app UI never turns `"failed"` — it
+   * stays `"processing"` indefinitely. Bound your poll loop with a timeout.
+   *
+   * @param job - The import job to inspect.
+   * @returns the {@linkcode ImportJobStatus}.
+   * @throws {@link HandleInvalidError} if the job handle is unknown.
+   *
+   * @examplePrompt What's the status of my DWG import?
+   * @examplePrompt Is the CAD import still processing?
+   * @examplePrompt Check where the import job is up to
+   * @examplePrompt Did the import job fail?
+   *
+   * # Example
+   * ```ts
+   * const job = await snaptrude.core.io.import.dwg(url, 1)
+   * console.log(await snaptrude.core.io.job.getStatus(job)) // "processing"
+   * ```
+   */
+  public abstract getStatus(job: ImportJobHandle): PluginApiReturn<ImportJobStatus>
+
+  /**
+   * Whether the job has finished successfully (status is `"complete"` and a
+   * result is ready). Returns `false` while pending/processing and on failure.
+   *
+   * @param job - The import job to inspect.
+   * @throws {@link HandleInvalidError} if the job handle is unknown.
+   *
+   * @examplePrompt Is the DWG import done yet?
+   * @examplePrompt Has the CAD import finished?
+   * @examplePrompt Tell me when the import job completes
+   * @examplePrompt Is my import ready?
+   *
+   * # Example
+   * ```ts
+   * const job = await snaptrude.core.io.import.dwg(url, 1)
+   * const deadline = Date.now() + 5 * 60_000 // cap the poll — see getStatus limitation
+   * while (!(await snaptrude.core.io.job.isComplete(job))) {
+   *   if (Date.now() > deadline) throw new Error("DWG import timed out")
+   *   await new Promise((r) => setTimeout(r, 2000))
+   * }
+   * ```
+   */
+  public abstract isComplete(job: ImportJobHandle): PluginApiReturn<boolean>
+
+  /**
+   * The imported result once the job is complete — the placed
+   * {@linkcode UnderlayHandle}. Returns `null` while the job is still
+   * pending/processing or if it failed (check {@link PluginCoreIoJobApi.getError}).
+   *
+   * @param job - The completed import job.
+   * @throws {@link HandleInvalidError} if the job handle is unknown.
+   *
+   * @examplePrompt Get the underlay from my finished DWG import
+   * @examplePrompt Give me the result of the CAD import job
+   * @examplePrompt Fetch the imported CAD sketch once it's ready
+   * @examplePrompt Return the handle for the completed import
+   *
+   * # Example
+   * ```ts
+   * const job = await snaptrude.core.io.import.dwg(url, 1)
+   * const deadline = Date.now() + 5 * 60_000
+   * while (!(await snaptrude.core.io.job.isComplete(job))) {
+   *   if (Date.now() > deadline) throw new Error("DWG import timed out")
+   *   await new Promise((r) => setTimeout(r, 2000))
+   * }
+   * // DWG results are CAD underlays (CAD scaling isn't supported); manage them
+   * // via core.io.underlay.* (list / setOpacity / delete).
+   * const cad = await snaptrude.core.io.job.getResult(job)
+   * if (cad) console.log("import complete:", cad)
+   * ```
+   */
+  public abstract getResult(job: ImportJobHandle): PluginApiReturn<UnderlayHandle | null>
+
+  /**
+   * The failure message if the job's status is `"failed"`; otherwise `null`.
+   *
+   * @param job - The import job to inspect.
+   * @throws {@link HandleInvalidError} if the job handle is unknown.
+   *
+   * @examplePrompt Why did my DWG import fail?
+   * @examplePrompt What went wrong with the CAD import?
+   * @examplePrompt Show the error from the failed import job
+   * @examplePrompt Did the import error out, and why?
+   *
+   * # Example
+   * ```ts
+   * const job = await snaptrude.core.io.import.dwg(url, 1)
+   * if ((await snaptrude.core.io.job.getStatus(job)) === "failed") {
+   *   console.error(await snaptrude.core.io.job.getError(job))
+   * }
+   * ```
+   */
+  public abstract getError(job: ImportJobHandle): PluginApiReturn<string | null>
+}
+
+/** Lifecycle status of an asynchronous import job. */
+export const ImportJobStatus = z.enum(["pending", "processing", "complete", "failed"])
+export type ImportJobStatus = z.infer<typeof ImportJobStatus>
+
+/**
+ * Arguments for the `core.io.job.*` readers.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `job` | {@link ImportJobHandle} | The import job to inspect |
+ */
+export const PluginImportJobArgs = z.object({
+  job: ImportJobHandle,
+})
+export type PluginImportJobArgs = z.infer<typeof PluginImportJobArgs>

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

@@ -1,71 +1,71 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../../types"
-import { CadJsonInput } from "../import"
-
-/**
- * Import queries — read metadata about a source **before** importing it.
- *
- * These reads let a plugin discover a source's shape before importing it:
- * how many pages a PDF has (for `import.pdf`'s `page`), and which CAD layers a
- * drawing defines (imports always bring in every layer — there is no filter —
- * but the names tell you what the drawing contains).
- *
- * Accessed via `snaptrude.core.io.query`.
- */
-export abstract class PluginCoreIoQueryApi {
-  constructor() {}
-
-  /**
-   * Count the pages of a PDF without importing it. `null` if the source can't be
-   * read as a PDF.
-   *
-   * @param source - The PDF: an `https://` URL or a `data:` URL.
-   * @returns the page count, or `null`.
-   *
-   * @examplePrompt How many pages does this PDF have?
-   * @examplePrompt Count the pages in the drawing set before importing
-   * @examplePrompt Get the PDF page count
-   * @examplePrompt Is this a multi-page PDF, and how many?
-   *
-   * # Example
-   * ```ts
-   * const pages = await snaptrude.core.io.query.getPdfPageCount(url)
-   * for (let p = 1; p <= (pages ?? 0); p++) {
-   *   await snaptrude.core.io.import.pdf(url, p, p) // one page per storey
-   * }
-   * ```
-   */
-  public abstract getPdfPageCount(source: string): PluginApiReturn<number | null>
-
-  /**
-   * List the distinct CAD layer names tagged on a parsed CAD JSON's entities.
-   * Read-only inspection: imports always bring in **every** layer (there is no
-   * layer filter on {@link core.io.import.dwg} / {@link core.io.import.cadJson}) —
-   * use the names to decide whether to import at all, or what to tell the user.
-   *
-   * @param cad - Parsed CAD JSON (same shape `import.cadJson` accepts).
-   * @returns the layer names (empty array if none).
-   *
-   * @examplePrompt What CAD layers are in this drawing?
-   * @examplePrompt List the layers before importing the CAD
-   * @examplePrompt Show the DWG layer names so I can pick which to import
-   * @examplePrompt Enumerate the CAD JSON layers
-   *
-   * # Example
-   * ```ts
-   * const layers = await snaptrude.core.io.query.listCadLayers(cad)
-   * if (layers.some((l) => l.toUpperCase().includes("WALL"))) {
-   *   await snaptrude.core.io.import.cadJson(cad, 1) // all layers import together
-   * }
-   * ```
-   */
-  public abstract listCadLayers(cad: CadJsonInput): PluginApiReturn<string[]>
-}
-
-/** Arguments for {@link PluginCoreIoQueryApi.getPdfPageCount}. */
-export const PluginQueryPdfPageCountArgs = z.object({ source: z.string().min(1) })
-export type PluginQueryPdfPageCountArgs = z.infer<typeof PluginQueryPdfPageCountArgs>
-
-/** Arguments for {@link PluginCoreIoQueryApi.listCadLayers}. */
-export const PluginQueryCadLayersArgs = z.object({ cad: CadJsonInput })
-export type PluginQueryCadLayersArgs = z.infer<typeof PluginQueryCadLayersArgs>
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import { CadJsonInput } from "../import"
+
+/**
+ * Import queries — read metadata about a source **before** importing it.
+ *
+ * These reads let a plugin discover a source's shape before importing it:
+ * how many pages a PDF has (for `import.pdf`'s `page`), and which CAD layers a
+ * drawing defines (imports always bring in every layer — there is no filter —
+ * but the names tell you what the drawing contains).
+ *
+ * Accessed via `snaptrude.core.io.query`.
+ */
+export abstract class PluginCoreIoQueryApi {
+  constructor() {}
+
+  /**
+   * Count the pages of a PDF without importing it. `null` if the source can't be
+   * read as a PDF.
+   *
+   * @param source - The PDF: an `https://` URL or a `data:` URL.
+   * @returns the page count, or `null`.
+   *
+   * @examplePrompt How many pages does this PDF have?
+   * @examplePrompt Count the pages in the drawing set before importing
+   * @examplePrompt Get the PDF page count
+   * @examplePrompt Is this a multi-page PDF, and how many?
+   *
+   * # Example
+   * ```ts
+   * const pages = await snaptrude.core.io.query.getPdfPageCount(url)
+   * for (let p = 1; p <= (pages ?? 0); p++) {
+   *   await snaptrude.core.io.import.pdf(url, p, p) // one page per storey
+   * }
+   * ```
+   */
+  public abstract getPdfPageCount(source: string): PluginApiReturn<number | null>
+
+  /**
+   * List the distinct CAD layer names tagged on a parsed CAD JSON's entities.
+   * Read-only inspection: imports always bring in **every** layer (there is no
+   * layer filter on {@link core.io.import.dwg} / {@link core.io.import.cadJson}) —
+   * use the names to decide whether to import at all, or what to tell the user.
+   *
+   * @param cad - Parsed CAD JSON (same shape `import.cadJson` accepts).
+   * @returns the layer names (empty array if none).
+   *
+   * @examplePrompt What CAD layers are in this drawing?
+   * @examplePrompt List the layers before importing the CAD
+   * @examplePrompt Show the DWG layer names so I can pick which to import
+   * @examplePrompt Enumerate the CAD JSON layers
+   *
+   * # Example
+   * ```ts
+   * const layers = await snaptrude.core.io.query.listCadLayers(cad)
+   * if (layers.some((l) => l.toUpperCase().includes("WALL"))) {
+   *   await snaptrude.core.io.import.cadJson(cad, 1) // all layers import together
+   * }
+   * ```
+   */
+  public abstract listCadLayers(cad: CadJsonInput): PluginApiReturn<string[]>
+}
+
+/** Arguments for {@link PluginCoreIoQueryApi.getPdfPageCount}. */
+export const PluginQueryPdfPageCountArgs = z.object({ source: z.string().min(1) })
+export type PluginQueryPdfPageCountArgs = z.infer<typeof PluginQueryPdfPageCountArgs>
+
+/** Arguments for {@link PluginCoreIoQueryApi.listCadLayers}. */
+export const PluginQueryCadLayersArgs = z.object({ cad: CadJsonInput })
+export type PluginQueryCadLayersArgs = z.infer<typeof PluginQueryCadLayersArgs>