@snaptrude/plugin-core 0.9.8 → 0.9.10

package/src/api/workspace/index.ts

@@ -10,13 +10,16 @@ import { PluginApiReturn } from "../../types"
  * 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 switch for
+ * as a normal host error. It also carries the workspace-level mode switches for
  * Present mode ({@linkcode PluginWorkspaceApi.openPresentMode} /
- * {@linkcode PluginWorkspaceApi.closePresentMode}).
+ * {@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}. */
@@ -68,6 +71,52 @@ export abstract class PluginWorkspaceApi {
    */
   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() {}
 }