@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827135706

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

@@ -0,0 +1,496 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import {
+  Vec3Handle,
+  UnderlayHandle,
+  TerrainHandle,
+  ImportJobHandle,
+  ComponentHandle,
+} from "../../../../handles"
+
+/**
+ * A file `source` accepted by every importer: an `https://` URL or a `data:`
+ * URL (base64). Validated for shape at the boundary — other schemes (`http:`,
+ * `blob:`, `file:`) are rejected, since the host page (HTTPS) cannot fetch them.
+ */
+export const ImportSource = z
+  .string()
+  .min(1)
+  .refine((s) => s.startsWith("https://") || s.startsWith("data:"), {
+    message: "source must be an https:// URL or a data: URL",
+  })
+
+/**
+ * File import — bring external files into the Snaptrude **scene**.
+ *
+ * `core.io.import.*` ingests images, PDFs, CAD drawings, 3D models, and site
+ * terrain and commits them to the model as traceable underlays, placed geometry,
+ * or topography. It is the scene counterpart to `presentation.import.*` (which
+ * drops assets on the Present canvas, not the model).
+ *
+ * ## The `source` argument
+ * Every file importer takes a single `source` **string** — either an `https://`
+ * URL or a `data:` URL (base64). A plugin worker cannot hand a browser `File`
+ * across the boundary, so the host fetches `source` and rebuilds the `File`
+ * itself. Both forms go through the same path.
+ *
+ * ## Return values
+ * - `image` / `pdf` / `cadJson` → an {@linkcode UnderlayHandle} (a placed 2D
+ *   reference plane; drive it with `core.io.underlay.*`).
+ * - `dwg` → an {@linkcode ImportJobHandle} — DWG conversion is a long server job,
+ *   so `dwg` returns immediately and you poll it with `core.io.job.*`.
+ * - `model` → a {@linkcode ComponentHandle} (a placed 3D component).
+ * - `terrain` → a {@linkcode TerrainHandle} (the project's single site terrain).
+ *
+ * Every importer **throws** on failure (bad source, unsupported format, engine
+ * error). Accessed via `snaptrude.core.io.import`.
+ */
+export abstract class PluginCoreIoImportApi {
+  constructor() {}
+
+  /**
+   * Import a raster image as a scene **underlay** — a flat, textured reference
+   * plane placed on a storey that you can trace over.
+   *
+   * Supported formats: PNG, JPG/JPEG, BMP. The image is placed on the target
+   * storey's "Image" layer at ~50% opacity by default.
+   *
+   * To place the image on a **Present-mode sheet** instead of the scene, use
+   * `presentation.import.image`.
+   *
+   * The plane is placed at the storey origin (the engine's import placement);
+   * there is no placement parameter — calibrate size with
+   * {@link PluginCoreIoUnderlayApi.setScale} after import.
+   *
+   * @param source - The image to import: an `https://` URL or a `data:` URL.
+   * @param storey - Target storey number. Defaults to the active storey.
+   * @param scale - Initial uniform scale factor applied to the plane. Calibrate
+   *   precisely afterwards with {@link PluginCoreIoUnderlayApi.setScale}.
+   * @param opacity - Plane opacity, `0`..`1` (default ~`0.5`).
+   * @param label - A name for the created underlay.
+   * @returns the created {@linkcode UnderlayHandle}.
+   * @throws if writes are disabled, the source can't be loaded, the format is
+   *   unsupported, or the engine fails to place the plane.
+   *
+   * @examplePrompt Import this floor plan image onto the ground floor to trace over
+   * @examplePrompt Drop this survey PNG in as a reference underlay at 30% opacity
+   * @examplePrompt Add a site plan image on storey 2
+   * @examplePrompt Bring in a sketch to trace, faded to half opacity
+   *
+   * # Example
+   * ```ts
+   * // Place a floor plan on storey 1, then calibrate it to a real-world size.
+   * const plan = await snaptrude.core.io.import.image(
+   *   "https://example.com/floorplan.png",
+   *   1,           // storey
+   *   undefined,   // scale
+   *   0.4,         // opacity
+   *   "Ground floor plan",
+   * )
+   * // Make the plan's longest side exactly 40 project-units:
+   * await snaptrude.core.io.underlay.setScale(plan, { planSize: 40 })
+   * ```
+   */
+  public abstract image(
+    source: string,
+    storey?: number,
+    scale?: number,
+    opacity?: number,
+    label?: string,
+  ): PluginApiReturn<UnderlayHandle>
+
+  /**
+   * Import one page of a PDF as a scene **underlay** (a traceable reference plane).
+   *
+   * One PDF per storey, one page per call. To bring in several pages, call once
+   * per page onto different storeys.
+   *
+   * @param source - The PDF to import: an `https://` URL or a `data:` URL.
+   * @param storey - Target storey number. Defaults to the active storey.
+   * @param page - 1-based page number to import (multi-page PDFs). Default `1`.
+   * @param scale - A drawing-scale **label** that sizes the page in real-world
+   *   units, matching the project's unit mode: metric `"1:10"`..`"1:1000"` (e.g.
+   *   `"1:100"`) or imperial `` `1/8" = 1'` `` / `` `1" = 10'` ``. Must be a valid
+   *   label for the current unit mode (invalid → throws). Defaults to `"1:100"`
+   *   in metric projects and `` `1" = 1'` `` in imperial projects. Re-calibrate
+   *   afterwards with {@link PluginCoreIoUnderlayApi.setScale}.
+   * @param opacity - Plane opacity, `0`..`1` (default ~`0.5`).
+   * @returns the created {@linkcode UnderlayHandle}.
+   * @throws if writes are disabled, the source can't be loaded, the storey
+   *   already has a PDF, the page is out of range, the scale label is invalid for
+   *   the unit mode, or the engine fails.
+   *
+   * @examplePrompt Import page 1 of this PDF floor plan onto storey 1
+   * @examplePrompt Bring in the second page of this PDF as an underlay at 1:50
+   * @examplePrompt Add this PDF plan to the ground floor to trace over
+   * @examplePrompt Place page 3 of the drawing set on storey 3
+   *
+   * # Example
+   * ```ts
+   * const sheet = await snaptrude.core.io.import.pdf(
+   *   "https://example.com/plans.pdf",
+   *   1,        // storey
+   *   2,        // page
+   *   "1:100",  // drawing scale
+   * )
+   * ```
+   */
+  public abstract pdf(
+    source: string,
+    storey?: number,
+    page?: number,
+    scale?: string,
+    opacity?: number,
+  ): PluginApiReturn<UnderlayHandle>
+
+  /**
+   * Import a **DWG** CAD drawing as a scene underlay. `.dwg` only (no DXF).
+   *
+   * DWG conversion runs on a server and can take minutes, so this **starts a job
+   * and returns immediately** with an {@linkcode ImportJobHandle}. One CAD
+   * import runs at a time: starting a second while one is in flight throws —
+   * poll the first job to completion first. Poll it with
+   * {@link PluginCoreIoJobApi.isComplete} / {@link PluginCoreIoJobApi.getStatus}, then call
+   * {@link PluginCoreIoJobApi.getResult} to get the placed {@linkcode UnderlayHandle}.
+   * For CAD you already have parsed as JSON, use {@link PluginCoreIoImportApi.cadJson}
+   * (synchronous, no server round-trip).
+   *
+   * All CAD layers are imported (there is no layer filter).
+   *
+   * @param source - The `.dwg` file: an `https://` URL or a `data:` URL.
+   * @param storey - Target storey number. Defaults to the active storey.
+   * @returns an {@linkcode ImportJobHandle} to poll via `core.io.job.*`.
+   * @throws if writes are disabled or the upload cannot be started. (Conversion
+   *   failures surface later via {@link PluginCoreIoJobApi.getError}.)
+   *
+   * @examplePrompt Import this DWG floor plan onto storey 1
+   * @examplePrompt Bring in a CAD drawing as an underlay and tell me when it's ready
+   * @examplePrompt Start importing this CAD file onto the ground floor
+   *
+   * # Example
+   * ```ts
+   * const job = await snaptrude.core.io.import.dwg("https://example.com/plan.dwg", 1)
+   * // Poll until the server-side conversion finishes — always with a timeout
+   * // (a UI-cancelled import stays "processing" forever).
+   * 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))
+   * }
+   * // The DWG lands as a CAD underlay. CAD scaling isn't supported; manage it
+   * // (list / fade / delete) via core.io.underlay.*.
+   * const cad = await snaptrude.core.io.job.getResult(job)
+   * if (cad) console.log("DWG imported as CAD underlay:", cad)
+   * ```
+   */
+  public abstract dwg(source: string, storey?: number): PluginApiReturn<ImportJobHandle>
+
+  /**
+   * Sketch a CAD underlay from **already-parsed CAD JSON** — synchronous, with no
+   * server round-trip. Use this when you hold parsed CAD data (e.g. produced by
+   * your own converter); use {@link PluginCoreIoImportApi.dwg} for raw `.dwg`
+   * files.
+   *
+   * All layers in the JSON are sketched (there is no layer filter), at the
+   * drawing's own coordinates.
+   *
+   * @param cad - The parsed CAD data: `{ unit, geometry: [...] }` describing the
+   *   drawing's lines/arcs/layers.
+   * @param storey - Target storey number. Defaults to the active storey.
+   * @returns the created {@linkcode UnderlayHandle}.
+   * @throws if writes are disabled, the JSON yields no drawable geometry, or the
+   *   drawing is out of bounds.
+   *
+   * @examplePrompt Sketch this parsed CAD JSON onto the active storey
+   * @examplePrompt Draw these CAD curves as an underlay on storey 2
+   * @examplePrompt Create a CAD sketch from this geometry data
+   * @examplePrompt Import my converted CAD JSON onto the ground floor
+   *
+   * # Example
+   * ```ts
+   * const cad = await snaptrude.core.io.import.cadJson(
+   *   { unit: "mm", geometry: [{ type: "line", layer: "WALLS", ... }] },
+   *   1,
+   * )
+   * ```
+   */
+  public abstract cadJson(cad: CadJsonInput, storey?: number): PluginApiReturn<UnderlayHandle>
+
+  /**
+   * Import a **3D model** file and place it in the scene as a component.
+   *
+   * Supported formats: SketchUp (`.skp`), FBX (`.fbx`), OBJ (`.obj`), 3DS
+   * (`.3ds`), and zipped bundles (`.zip`). The file is converted on the server,
+   * then placed. `.glb`/`.gltf`/`.ifc`/`.stl` and Rhino/Revit are not supported.
+   *
+   * The model is placed at its source dimensions (interpreted in the file's own
+   * units); there is no import-time scale override.
+   *
+   * Unlike `dwg`, this call **waits for the server conversion**: a large model
+   * may exceed the 60-second call cap and reject at the API boundary while the
+   * import still completes in the background (the model then appears without a
+   * handle being returned — re-query the scene to find it). Keep sources small.
+   *
+   * @param source - The model file: an `https://` URL or a `data:` URL.
+   * @param storey - Target storey number. Defaults to the active storey.
+   * @param format - The file's format. Inferred from `source` when omitted.
+   * @param position - Where to place the model. Defaults to the storey origin.
+   * @param label - A name for the placed component.
+   * @returns the placed {@linkcode ComponentHandle}.
+   * @throws if writes are disabled, the source can't be loaded, the format is
+   *   unsupported, conversion/placement fails, or the converted model cannot be
+   *   found in the library after upload.
+   *
+   * @examplePrompt Import this SketchUp model onto storey 1
+   * @examplePrompt Bring in this OBJ file and place it at the origin
+   * @examplePrompt Add this 3D model to the ground floor
+   *
+   * # Example
+   * ```ts
+   * const model = await snaptrude.core.io.import.model(
+   *   "https://example.com/tree.skp",
+   *   1,        // storey
+   *   "skp",
+   * )
+   * ```
+   */
+  public abstract model(
+    source: string,
+    storey?: number,
+    format?: ModelFormat,
+    position?: Vec3Handle,
+    label?: string,
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Import **site terrain** for a location — Mapbox topography (elevation +
+   * satellite/streets imagery, optional neighborhood buildings and parcels).
+   *
+   * One terrain per project (a singleton). `width`/`length` describe the
+   * real-world extent of the area to load **in metres** (regardless of the
+   * project's unit mode); the host converts them to the right map zoom
+   * internally — you do not pass a zoom level.
+   *
+   * @param lat - Site latitude (degrees), `-90`..`90`.
+   * @param lng - Site longitude (degrees), `-180`..`180`.
+   * @param width - East–west extent of the area to load, in metres.
+   * @param length - North–south extent of the area to load, in metres.
+   * @param elevation - Include DEM elevation (a real terrain surface). Default `true`.
+   * @param satellite - Drape satellite imagery. Default `true`.
+   * @param neighborhood - Include surrounding context buildings. Default `false`.
+   * @param parcels - Include site parcel boundaries. Default `false`.
+   * @returns the created {@linkcode TerrainHandle}.
+   * @throws if writes are disabled, a terrain already exists, or the map/mesh
+   *   generation fails.
+   *
+   * @examplePrompt Import the site terrain for this location, about 500m across
+   * @examplePrompt Load the topography at 40.7128, -74.0060 for a 300 by 300 meter site
+   * @examplePrompt Bring in satellite terrain for the site with the surrounding buildings
+   * @examplePrompt Add site elevation for a 1km by 1km area at these coordinates
+   *
+   * # Example
+   * ```ts
+   * // 300m × 300m site with elevation + satellite imagery.
+   * const terrain = await snaptrude.core.io.import.terrain(
+   *   40.7128,  // lat
+   *   -74.006,  // lng
+   *   300,      // width  (metres)
+   *   300,      // length (metres)
+   *   true,     // elevation
+   *   true,     // satellite
+   * )
+   * ```
+   */
+  public abstract terrain(
+    lat: number,
+    lng: number,
+    width: number,
+    length: number,
+    elevation?: boolean,
+    satellite?: boolean,
+    neighborhood?: boolean,
+    parcels?: boolean,
+  ): PluginApiReturn<TerrainHandle>
+
+  /**
+   * Import an **EPW weather file** into the project's weather catalog.
+   *
+   * Uploads an EnergyPlus Weather (`.epw`) file and registers it as the
+   * project's site weather, returning its catalog `weatherFileId` — the same id
+   * {@link PluginAnalysisWeatherApi.getSeries}, `program.site.getWeather`, and a
+   * daylight run's provenance report. Uploading a user file makes the site's
+   * `selectionMethod` `"user-upload"`, overriding nearest-station resolution.
+   *
+   * **Mutating**: this writes project state and is subject to the plugin
+   * write-gate — it throws when plugin writes are disabled. Unlike the file
+   * underlay/model importers it returns no scene handle (a weather file is not
+   * a scene object), only the catalog `{ weatherFileId, label }`.
+   *
+   * @param source - The `.epw` file to import: an `https://` URL or a `data:` URL.
+   * @returns A {@linkcode PluginImportEpwResult} — the catalog `weatherFileId`
+   *   and a human-readable `label` (the station/file name).
+   * @throws if writes are disabled, the source can't be loaded, or the file is
+   *   not a valid EPW.
+   *
+   * @examplePrompt Import this EPW weather file for the site
+   * @examplePrompt Upload a custom weather file for the daylight analysis
+   * @examplePrompt Use this .epw as the project's weather source
+   *
+   * # Example
+   * ```ts
+   * const { weatherFileId, label } = await snaptrude.core.io.import.epw(
+   *   "https://example.com/Chicago-OHare.epw",
+   * )
+   * console.log(`Weather set to ${label} (${weatherFileId})`)
+   * ```
+   */
+  public abstract epw(source: string): PluginApiReturn<PluginImportEpwResult>
+}
+
+/**
+ * Supported 3D model import formats. `.glb`/`.gltf`/`.ifc`/`.stl` and Rhino/Revit
+ * are intentionally excluded (no in-app import path).
+ */
+export const ModelFormat = z.enum(["skp", "fbx", "obj", "3ds", "zip"])
+export type ModelFormat = z.infer<typeof ModelFormat>
+
+/**
+ * Parsed CAD JSON accepted by {@link PluginCoreIoImportApi.cadJson}. `unit` sets
+ * the drawing's length unit; `geometry` is the array of CAD entities (lines,
+ * polylines, arcs, circles), each tagged with its CAD `layer`. Additional fields
+ * are passed through untouched.
+ */
+export const CadJsonInput = z
+  .object({
+    unit: z.string().optional(),
+    geometry: z.array(z.record(z.string(), z.unknown())).optional(),
+  })
+  .passthrough()
+export type CadJsonInput = z.infer<typeof CadJsonInput>
+
+/**
+ * Arguments for {@link PluginCoreIoImportApi.image}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `source` | `string` | Image `https://` URL or `data:` URL (png/jpg/jpeg/bmp) |
+ * | `storey` | `number`? | Target storey (default: active) |
+ * | `scale` | `number`? | Initial uniform scale |
+ * | `opacity` | `number`? | `0`..`1` (default ~`0.5`) |
+ * | `label` | `string`? | Name for the underlay |
+ */
+export const PluginImportImageArgs = z.object({
+  source: ImportSource,
+  storey: z.number().int().optional(),
+  scale: z.number().positive().optional(),
+  opacity: z.number().min(0).max(1).optional(),
+  label: z.string().optional(),
+})
+export type PluginImportImageArgs = z.infer<typeof PluginImportImageArgs>
+
+/**
+ * Arguments for {@link PluginCoreIoImportApi.pdf}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `source` | `string` | PDF `https://` URL or `data:` URL |
+ * | `storey` | `number`? | Target storey (default: active) |
+ * | `page` | `number`? | 1-based page (default `1`) |
+ * | `scale` | `string`? | Drawing-scale label, e.g. `"1:100"` |
+ * | `opacity` | `number`? | `0`..`1` (default ~`0.5`) |
+ */
+export const PluginImportPdfArgs = z.object({
+  source: ImportSource,
+  storey: z.number().int().optional(),
+  page: z.number().int().positive().optional(),
+  scale: z.string().optional(),
+  opacity: z.number().min(0).max(1).optional(),
+})
+export type PluginImportPdfArgs = z.infer<typeof PluginImportPdfArgs>
+
+/** Arguments for {@link PluginCoreIoImportApi.dwg}. */
+export const PluginImportDwgArgs = z.object({
+  source: ImportSource,
+  storey: z.number().int().optional(),
+})
+export type PluginImportDwgArgs = z.infer<typeof PluginImportDwgArgs>
+
+/** Arguments for {@link PluginCoreIoImportApi.cadJson}. */
+export const PluginImportCadJsonArgs = z.object({
+  cad: CadJsonInput,
+  storey: z.number().int().optional(),
+})
+export type PluginImportCadJsonArgs = z.infer<typeof PluginImportCadJsonArgs>
+
+/**
+ * Arguments for {@link PluginCoreIoImportApi.model}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `source` | `string` | Model `https://` URL or `data:` URL |
+ * | `storey` | `number`? | Target storey (default: active) |
+ * | `format` | {@link ModelFormat}? | File format (inferred when omitted) |
+ * | `position` | {@link Vec3Handle}? | Placement (default: storey origin) |
+ * | `label` | `string`? | Name for the component |
+ */
+export const PluginImportModelArgs = z.object({
+  source: ImportSource,
+  storey: z.number().int().optional(),
+  format: ModelFormat.optional(),
+  position: Vec3Handle.optional(),
+  label: z.string().optional(),
+})
+export type PluginImportModelArgs = z.infer<typeof PluginImportModelArgs>
+
+/**
+ * Arguments for {@link PluginCoreIoImportApi.terrain}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `lat` | `number` | Latitude (degrees), `-90`..`90` |
+ * | `lng` | `number` | Longitude (degrees), `-180`..`180` |
+ * | `width` | `number` | East–west extent, metres |
+ * | `length` | `number` | North–south extent, metres |
+ * | `elevation` | `boolean`? | Include DEM elevation (default `true`) |
+ * | `satellite` | `boolean`? | Drape satellite imagery (default `true`) |
+ * | `neighborhood` | `boolean`? | Include context buildings (default `false`) |
+ * | `parcels` | `boolean`? | Include parcel boundaries (default `false`) |
+ */
+export const PluginImportTerrainArgs = z.object({
+  lat: z.number().min(-90).max(90),
+  lng: z.number().min(-180).max(180),
+  width: z.number().positive().finite(),
+  length: z.number().positive().finite(),
+  elevation: z.boolean().optional(),
+  satellite: z.boolean().optional(),
+  neighborhood: z.boolean().optional(),
+  parcels: z.boolean().optional(),
+})
+export type PluginImportTerrainArgs = z.infer<typeof PluginImportTerrainArgs>
+
+/**
+ * Arguments for {@link PluginCoreIoImportApi.epw}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `source` | `string` | EPW `https://` URL or `data:` URL |
+ */
+export const PluginImportEpwArgs = z.object({
+  source: ImportSource,
+})
+export type PluginImportEpwArgs = z.infer<typeof PluginImportEpwArgs>
+
+/**
+ * Result of {@link PluginCoreIoImportApi.epw} — the imported weather file's
+ * catalog entry.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `weatherFileId` | `string` | Catalog id (same key as `analysis.weather`'s `weatherFileId`) |
+ * | `label` | `string` | Human-readable name (station / file name) |
+ */
+export const PluginImportEpwResult = z.object({
+  weatherFileId: z.string(),
+  label: z.string(),
+})
+export type PluginImportEpwResult = z.infer<typeof PluginImportEpwResult>

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

@@ -0,0 +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"

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

@@ -0,0 +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>