@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/src/api/workspace/index.ts

@@ -0,0 +1,612 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * `snaptrude.workspace.*` — the dashboard surface: projects and teams outside the
+ * open canvas.
+ *
+ * This namespace reads and creates the containers a design lives in — the
+ * project itself and the team it belongs to — mirroring the Snaptrude dashboard.
+ * Teams are **read-only** here (no create/invite/delete in v1, a deliberate
+ * safety decision); there are no folders in v1. A `projectId` is the project's
+ * floorkey. Plan limits are enforced by the backend — a limit rejection surfaces
+ * as a normal host error. It also carries the workspace-level mode switches for
+ * Present mode ({@linkcode PluginWorkspaceApi.openPresentMode} /
+ * {@linkcode PluginWorkspaceApi.closePresentMode}) and Program mode
+ * ({@linkcode PluginWorkspaceApi.openProgramMode} /
+ * {@linkcode PluginWorkspaceApi.closeProgramMode}).
+ *
+ * - {@linkcode PluginWorkspaceApi.projects} — Create, copy, list, read & rename projects
+ * - {@linkcode PluginWorkspaceApi.teams} — Read teams and their members
+ * - {@linkcode PluginWorkspaceApi.openPresentMode} / {@linkcode PluginWorkspaceApi.closePresentMode} — Open/close the Present-mode documentation editor
+ * - {@linkcode PluginWorkspaceApi.openProgramMode} / {@linkcode PluginWorkspaceApi.closeProgramMode} — Open/close the Program tab (the spreadsheet the `program.spreadsheet.*` calls run in)
+ */
+export abstract class PluginWorkspaceApi {
+  /** Projects — create, copy, list, read & rename. See {@linkcode PluginWorkspaceProjectsApi}. */
+  public abstract projects: PluginWorkspaceProjectsApi
+  /** Teams — read teams and their members. See {@linkcode PluginWorkspaceTeamsApi}. */
+  public abstract teams: PluginWorkspaceTeamsApi
+
+  /**
+   * Open Present mode — the documentation editor the `presentation.*`
+   * namespaces operate on.
+   *
+   * Switches the workspace into Present mode and resolves only once the
+   * Present canvas has finished mounting (waits up to ~15s; a mount that
+   * never completes is refused with a typed `PRECONDITION_FAILED`), so a
+   * `presentation.*` call issued right after this resolves finds Present
+   * mode open. Idempotent — resolves immediately when Present mode is
+   * already open. Write-gated: switching the mode under the user's feet is
+   * approval-controlled by design.
+   *
+   * @throws `PRECONDITION_FAILED` if the Present canvas does not mount within
+   *   the timeout.
+   *
+   * @examplePrompt Open present mode
+   * @examplePrompt Switch to the presentation editor
+   * @examplePrompt Open the sheets so I can lay out views
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.workspace.openPresentMode()
+   * const { sheets } = await snaptrude.presentation.sheets.list()
+   * ```
+   */
+  public abstract openPresentMode(): PluginApiReturn<void>
+
+  /**
+   * Close Present mode and return to the modeling canvas.
+   *
+   * Idempotent — a no-op when Present mode is not open. Write-gated, like
+   * {@linkcode PluginWorkspaceApi.openPresentMode}.
+   *
+   * @examplePrompt Close present mode
+   * @examplePrompt Exit the presentation editor
+   * @examplePrompt Go back to the modeling canvas
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.workspace.closePresentMode()
+   * ```
+   */
+  public abstract closePresentMode(): PluginApiReturn<void>
+
+  /**
+   * Open Program mode — the Program tab the `program.spreadsheet.*` calls run in.
+   *
+   * Runs the top bar's own Program-button sequence (remember the preference,
+   * open or re-link the paired Program window) and resolves only once that tab
+   * has connected to the editor over its channel, so a `program.spreadsheet.*`
+   * call issued right after this resolves finds the tab open. The open happens
+   * outside a user gesture, so the browser may block the pop-up; the editor
+   * then shows its "Allow pop-up to continue" modal and this call keeps waiting
+   * (up to ~90s) for the user to confirm. Idempotent — resolves immediately
+   * when the Program tab is already connected, and is a no-op when the plugin is
+   * itself running in the Program tab. Write-gated.
+   *
+   * @throws `PRECONDITION_FAILED` if the user dismisses the pop-up modal or the
+   *   Program tab does not connect within the timeout.
+   *
+   * @examplePrompt Open program mode
+   * @examplePrompt Open the Program tab so I can build a custom sheet
+   * @examplePrompt Switch to the program spreadsheet
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.workspace.openProgramMode()
+   * const { sheets } = await snaptrude.program.spreadsheet.listSheets()
+   * ```
+   */
+  public abstract openProgramMode(): PluginApiReturn<void>
+
+  /**
+   * Close the Program tab.
+   *
+   * Idempotent — a no-op when no Program tab is connected. Write-gated, like
+   * {@linkcode PluginWorkspaceApi.openProgramMode}.
+   *
+   * @throws `PRECONDITION_FAILED` if the tab is still connected after ~15s.
+   *
+   * @examplePrompt Close program mode
+   * @examplePrompt Close the Program tab
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.workspace.closeProgramMode()
+   * ```
+   */
+  public abstract closeProgramMode(): PluginApiReturn<void>
+
+  constructor() {}
+}
+
+/**
+ * `workspace.projects.*` — create, copy, list, read & rename projects.
+ *
+ * A **project** is a single Snaptrude model, identified by its `projectId`
+ * (floorkey). Reads never throw for a miss ({@linkcode PluginWorkspaceProjectsApi.get}
+ * returns `null`). Create/copy/rename go through the backend, which enforces plan
+ * limits — a rejection surfaces as a normal host error.
+ *
+ * Accessed via `snaptrude.workspace.projects`.
+ */
+export abstract class PluginWorkspaceProjectsApi {
+  constructor() {}
+
+  /**
+   * Create a new, empty BIM project.
+   *
+   * Creates the project on the backend and returns its `projectId` (floorkey).
+   * Pass `options.teamId` to create it inside a team (otherwise it lands in the
+   * user's personal workspace) and `options.unit` to set the default length unit.
+   *
+   * @param name - Display name of the new project.
+   * @param options - Optional `unit` (default length unit) and `teamId` (owning team).
+   * @returns The new project's `projectId`.
+   * @throws If the backend rejects the create (e.g. a plan project limit).
+   *
+   * @examplePrompt Create a new project called Tower Study
+   * @examplePrompt Start a new project in the Acme team
+   * @examplePrompt Make a fresh project using millimeters
+   * @examplePrompt Create an empty project for me to work in
+   *
+   * # Example
+   * ```ts
+   * const { projectId } = await snaptrude.workspace.projects.create("Tower Study", {
+   *   teamId: "team_1",
+   *   unit: "mm",
+   * })
+   * ```
+   */
+  public abstract create(
+    name: string,
+    options?: { unit?: string; teamId?: string },
+  ): PluginApiReturn<PluginWorkspaceProjectsCreateResult>
+
+  /**
+   * Copy the **current** project into a new project — the dashboard's "Save As".
+   *
+   * Duplicates the project that is currently open into a new project with the
+   * given name, and returns the new `projectId`. Pass `options.teamId` to place
+   * the copy in a specific team.
+   *
+   * @param name - Display name for the copy.
+   * @param options - Optional `teamId` (team to place the copy in).
+   * @returns The new project's `projectId`.
+   * @throws If the backend rejects the copy (e.g. a plan project limit).
+   *
+   * @examplePrompt Save this project as a new copy called Tower Study v2
+   * @examplePrompt Duplicate the current project into the Acme team
+   * @examplePrompt Make a copy of this project so I can try changes
+   *
+   * # Example
+   * ```ts
+   * const { projectId } = await snaptrude.workspace.projects.copy("Tower Study v2")
+   * ```
+   */
+  public abstract copy(
+    name: string,
+    options?: { teamId?: string },
+  ): PluginApiReturn<PluginWorkspaceProjectsCopyResult>
+
+  /**
+   * List the projects the user can access.
+   *
+   * Returns a {@linkcode PluginProjectRef} per project. Pass `options.teamId` to
+   * scope the list to a single team; omit it for the user's accessible projects.
+   *
+   * @param options - Optional `teamId` filter.
+   * @returns A {@linkcode PluginWorkspaceProjectsListResult} with a `projects`
+   *   array (empty when there are none).
+   *
+   * @examplePrompt List all my projects
+   * @examplePrompt Show the projects in the Acme team
+   * @examplePrompt How many projects do I have?
+   * @examplePrompt What projects can I open?
+   *
+   * # Example
+   * ```ts
+   * const { projects } = await snaptrude.workspace.projects.list({ teamId: "team_1" })
+   * for (const p of projects) console.log(p.id, p.name)
+   * ```
+   */
+  public abstract list(
+    options?: { teamId?: string },
+  ): PluginApiReturn<PluginWorkspaceProjectsListResult>
+
+  /**
+   * Get a single project by id.
+   *
+   * @param projectId - The project's `projectId` (floorkey).
+   * @returns The matching {@linkcode PluginProjectRef}, or `null` if no project
+   *   has that id / the user cannot access it.
+   *
+   * @examplePrompt Get the project with this id
+   * @examplePrompt Look up a project by its floorkey
+   * @examplePrompt What is the name of this project?
+   *
+   * # Example
+   * ```ts
+   * const project = await snaptrude.workspace.projects.get("floorkey_123")
+   * if (project) console.log(project.name)
+   * ```
+   */
+  public abstract get(
+    projectId: string,
+  ): PluginApiReturn<PluginWorkspaceProjectsGetResult>
+
+  /**
+   * Rename a project.
+   *
+   * @param projectId - The project's `projectId` (floorkey).
+   * @param name - The project's new display name.
+   * @returns The renamed project's `projectId`.
+   * @throws If no project has the given id or the rename is rejected.
+   *
+   * @examplePrompt Rename this project to Tower Study Final
+   * @examplePrompt Change the name of project floorkey_123
+   * @examplePrompt Give this project a new name
+   *
+   * # Example
+   * ```ts
+   * const { projectId } = await snaptrude.workspace.projects.rename(
+   *   "floorkey_123",
+   *   "Tower Study Final",
+   * )
+   * ```
+   */
+  public abstract rename(
+    projectId: string,
+    name: string,
+  ): PluginApiReturn<PluginWorkspaceProjectsRenameResult>
+}
+
+/**
+ * `workspace.teams.*` — read teams and their members.
+ *
+ * A **team** is a shared workspace that owns projects and members. **Read-only**
+ * in v1: there is no create/invite/delete (a deliberate safety decision). Reads
+ * never throw for a miss ({@linkcode PluginWorkspaceTeamsApi.get} returns `null`).
+ *
+ * Accessed via `snaptrude.workspace.teams`.
+ */
+export abstract class PluginWorkspaceTeamsApi {
+  constructor() {}
+
+  /**
+   * List the teams the user belongs to.
+   *
+   * @returns A {@linkcode PluginWorkspaceTeamsListResult} with a `teams` array
+   *   (empty when the user belongs to none).
+   *
+   * @examplePrompt List all my teams
+   * @examplePrompt Which teams am I a member of?
+   * @examplePrompt Show every team I can access
+   *
+   * # Example
+   * ```ts
+   * const { teams } = await snaptrude.workspace.teams.list()
+   * for (const t of teams) console.log(t.id, t.name)
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginWorkspaceTeamsListResult>
+
+  /**
+   * Get a single team by id.
+   *
+   * @param teamId - The id of the team to read.
+   * @returns The matching {@linkcode PluginTeamRef}, or `null` if no team has that
+   *   id / the user is not a member.
+   *
+   * @examplePrompt Get the team with id team_1
+   * @examplePrompt Look up a team by its id
+   * @examplePrompt What is the name of this team?
+   *
+   * # Example
+   * ```ts
+   * const team = await snaptrude.workspace.teams.get("team_1")
+   * if (team) console.log(team.name)
+   * ```
+   */
+  public abstract get(
+    teamId: string,
+  ): PluginApiReturn<PluginWorkspaceTeamsGetResult>
+
+  /**
+   * List the members of a team.
+   *
+   * @param teamId - The id of the team whose members to list.
+   * @returns A {@linkcode PluginWorkspaceTeamsListMembersResult} with a `members`
+   *   array (empty when the team has none / is missing).
+   *
+   * @examplePrompt List the members of the Acme team
+   * @examplePrompt Who is on team_1?
+   * @examplePrompt How many people are in this team?
+   *
+   * # Example
+   * ```ts
+   * const { members } = await snaptrude.workspace.teams.listMembers("team_1")
+   * for (const m of members) console.log(m.name, m.email)
+   * ```
+   */
+  public abstract listMembers(
+    teamId: string,
+  ): PluginApiReturn<PluginWorkspaceTeamsListMembersResult>
+}
+
+// ---------------------------------------------------------------------------
+// DTOs — conservative, never raw backend payloads
+// ---------------------------------------------------------------------------
+
+/**
+ * A project reference — a conservative projection of a project, never the raw
+ * backend payload.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The project's `projectId` (floorkey) |
+ * | `name` | `string` | Display name |
+ * | `teamId` | `string?` | Owning team id (absent for personal projects) |
+ * | `createdAt` | `string?` | Creation timestamp (ISO 8601) when known |
+ * | `modifiedAt` | `string?` | Last-modified timestamp (ISO 8601) when known |
+ */
+export const PluginProjectRef = z.object({
+  id: z.string(),
+  name: z.string(),
+  teamId: z.string().optional(),
+  createdAt: z.string().optional(),
+  modifiedAt: z.string().optional(),
+})
+export type PluginProjectRef = z.infer<typeof PluginProjectRef>
+
+/**
+ * A team reference — a conservative projection of a team, never the raw backend
+ * payload.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable team id |
+ * | `name` | `string` | Display name |
+ * | `role` | `string?` | The user's role in the team when known |
+ */
+export const PluginTeamRef = z.object({
+  id: z.string(),
+  name: z.string(),
+  role: z.string().optional(),
+})
+export type PluginTeamRef = z.infer<typeof PluginTeamRef>
+
+/**
+ * A team member reference — a conservative projection of a member, never the raw
+ * backend payload.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable user id |
+ * | `name` | `string` | Display name |
+ * | `email` | `string?` | Email address when known |
+ * | `role` | `string?` | The member's role in the team when known |
+ */
+export const PluginTeamMemberRef = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().optional(),
+  role: z.string().optional(),
+})
+export type PluginTeamMemberRef = z.infer<typeof PluginTeamMemberRef>
+
+// ---------------------------------------------------------------------------
+// projects — args + results
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginWorkspaceProjectsApi.create} (options flattened).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Display name of the new project |
+ * | `unit` | `string?` | Default length unit |
+ * | `teamId` | `string?` | Owning team id (personal workspace if omitted) |
+ */
+export const PluginWorkspaceProjectsCreateArgs = z.object({
+  name: z.string(),
+  unit: z.string().optional(),
+  teamId: z.string().optional(),
+})
+export type PluginWorkspaceProjectsCreateArgs = z.infer<
+  typeof PluginWorkspaceProjectsCreateArgs
+>
+
+/**
+ * Result of {@linkcode PluginWorkspaceProjectsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `projectId` | `string` | The id (floorkey) of the created project |
+ */
+export const PluginWorkspaceProjectsCreateResult = z.object({
+  projectId: z.string(),
+})
+export type PluginWorkspaceProjectsCreateResult = z.infer<
+  typeof PluginWorkspaceProjectsCreateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginWorkspaceProjectsApi.copy} (options flattened).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Display name for the copy |
+ * | `teamId` | `string?` | Team to place the copy in |
+ */
+export const PluginWorkspaceProjectsCopyArgs = z.object({
+  name: z.string(),
+  teamId: z.string().optional(),
+})
+export type PluginWorkspaceProjectsCopyArgs = z.infer<
+  typeof PluginWorkspaceProjectsCopyArgs
+>
+
+/**
+ * Result of {@linkcode PluginWorkspaceProjectsApi.copy}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `projectId` | `string` | The id (floorkey) of the copied project |
+ */
+export const PluginWorkspaceProjectsCopyResult = z.object({
+  projectId: z.string(),
+})
+export type PluginWorkspaceProjectsCopyResult = z.infer<
+  typeof PluginWorkspaceProjectsCopyResult
+>
+
+/**
+ * Arguments for {@linkcode PluginWorkspaceProjectsApi.list} (options flattened).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `teamId` | `string?` | Scope the list to this team; omit for all accessible projects |
+ */
+export const PluginWorkspaceProjectsListArgs = z.object({
+  teamId: z.string().optional(),
+})
+export type PluginWorkspaceProjectsListArgs = z.infer<
+  typeof PluginWorkspaceProjectsListArgs
+>
+
+/**
+ * Result of {@linkcode PluginWorkspaceProjectsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `projects` | {@linkcode PluginProjectRef}`[]` | Accessible projects (empty when none) |
+ */
+export const PluginWorkspaceProjectsListResult = z.object({
+  projects: z.array(PluginProjectRef),
+})
+export type PluginWorkspaceProjectsListResult = z.infer<
+  typeof PluginWorkspaceProjectsListResult
+>
+
+/**
+ * Arguments for {@linkcode PluginWorkspaceProjectsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `projectId` | `string` | The project's `projectId` (floorkey) |
+ */
+export const PluginWorkspaceProjectsGetArgs = z.object({
+  projectId: z.string(),
+})
+export type PluginWorkspaceProjectsGetArgs = z.infer<
+  typeof PluginWorkspaceProjectsGetArgs
+>
+
+/**
+ * Result of {@linkcode PluginWorkspaceProjectsApi.get} — the project, or `null`
+ * when no project has the given id.
+ */
+export const PluginWorkspaceProjectsGetResult = PluginProjectRef.nullable()
+export type PluginWorkspaceProjectsGetResult = z.infer<
+  typeof PluginWorkspaceProjectsGetResult
+>
+
+/**
+ * Arguments for {@linkcode PluginWorkspaceProjectsApi.rename}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `projectId` | `string` | The project's `projectId` (floorkey) |
+ * | `name` | `string` | The project's new display name |
+ */
+export const PluginWorkspaceProjectsRenameArgs = z.object({
+  projectId: z.string(),
+  name: z.string(),
+})
+export type PluginWorkspaceProjectsRenameArgs = z.infer<
+  typeof PluginWorkspaceProjectsRenameArgs
+>
+
+/**
+ * Result of {@linkcode PluginWorkspaceProjectsApi.rename}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `projectId` | `string` | The id (floorkey) of the renamed project |
+ */
+export const PluginWorkspaceProjectsRenameResult = z.object({
+  projectId: z.string(),
+})
+export type PluginWorkspaceProjectsRenameResult = z.infer<
+  typeof PluginWorkspaceProjectsRenameResult
+>
+
+// ---------------------------------------------------------------------------
+// teams — args + results
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of {@linkcode PluginWorkspaceTeamsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `teams` | {@linkcode PluginTeamRef}`[]` | The user's teams (empty when none) |
+ */
+export const PluginWorkspaceTeamsListResult = z.object({
+  teams: z.array(PluginTeamRef),
+})
+export type PluginWorkspaceTeamsListResult = z.infer<
+  typeof PluginWorkspaceTeamsListResult
+>
+
+/**
+ * Arguments for {@linkcode PluginWorkspaceTeamsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `teamId` | `string` | The id of the team to read |
+ */
+export const PluginWorkspaceTeamsGetArgs = z.object({
+  teamId: z.string(),
+})
+export type PluginWorkspaceTeamsGetArgs = z.infer<
+  typeof PluginWorkspaceTeamsGetArgs
+>
+
+/**
+ * Result of {@linkcode PluginWorkspaceTeamsApi.get} — the team, or `null` when no
+ * team has the given id.
+ */
+export const PluginWorkspaceTeamsGetResult = PluginTeamRef.nullable()
+export type PluginWorkspaceTeamsGetResult = z.infer<
+  typeof PluginWorkspaceTeamsGetResult
+>
+
+/**
+ * Arguments for {@linkcode PluginWorkspaceTeamsApi.listMembers}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `teamId` | `string` | The id of the team whose members to list |
+ */
+export const PluginWorkspaceTeamsListMembersArgs = z.object({
+  teamId: z.string(),
+})
+export type PluginWorkspaceTeamsListMembersArgs = z.infer<
+  typeof PluginWorkspaceTeamsListMembersArgs
+>
+
+/**
+ * Result of {@linkcode PluginWorkspaceTeamsApi.listMembers}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `members` | {@linkcode PluginTeamMemberRef}`[]` | The team's members (empty when none) |
+ */
+export const PluginWorkspaceTeamsListMembersResult = z.object({
+  members: z.array(PluginTeamMemberRef),
+})
+export type PluginWorkspaceTeamsListMembersResult = z.infer<
+  typeof PluginWorkspaceTeamsListMembersResult
+>