1// https://raw.githubusercontent.com/figma/plugin-typings/refs/heads/master/plugin-api-standalone.d.ts
2 
3/* plugin-typings are auto-generated. Do not update them directly. See developer-docs/ for instructions. */
4/**
5 * NOTE: This file is useful if you want to import specific types eg.
6 * import type { SceneNode } from "@figma/plugin-typings/plugin-api-standalone"
7 */
8/**
9 * @see https://developers.figma.com/docs/plugins/api/properties/figma-on
10 */
11declare type ArgFreeEventType =
12  | 'selectionchange'
13  | 'currentpagechange'
14  | 'close'
15  | 'timerstart'
16  | 'timerstop'
17  | 'timerpause'
18  | 'timerresume'
19  | 'timeradjust'
20  | 'timerdone'
21/**
22 * @see https://developers.figma.com/docs/plugins/api/figma
23 */
24interface PluginAPI {
25  /**
26   * The version of the Figma API this plugin is running on, as defined in your `manifest.json` in the `"api"` field.
27   */
28  readonly apiVersion: '1.0.0'
29  /**
30   * The currently executing command from the `manifest.json` file. It is the command string in the `ManifestMenuItem` (more details in the [manifest guide](https://developers.figma.com/docs/plugins/manifest)). If the plugin does not have any menu item, this property is undefined.
31   */
32  readonly command: string
33  /**
34   * The current editor type this plugin is running in. See also [Setting editor type](https://developers.figma.com/docs/plugins/setting-editor-type).
35   */
36  readonly editorType: 'figma' | 'figjam' | 'dev' | 'slides' | 'buzz'
37  /**
38   * Return the context the plugin is current running in.
39   *
40   * - `default` - The plugin is running as a normal plugin.
41   * - `textreview` - The plugin is running to provide text review functionality.
42   * - `inspect` - The plugin is running in the Inspect panel in Dev Mode.
43   * - `codegen` - The plugin is running in the Code section of the Inspect panel in Dev Mode.
44   * - `linkpreview` - The plugin is generating a link preview for a [Dev resource](https://help.figma.com/hc/en-us/articles/15023124644247#Add_external_links_and_resources_for_developers) in Dev Mode.
45   * - `auth` - The plugin is running to authenticate a user in Dev Mode.
46   *
47   * Caution: The `linkpreview` and `auth` modes are only available to partner and Figma-owned plugins.
48   *
49   * @remarks
50   * Here’s a simplified example where you can create an if statement in a plugin that has one set of functionality when it is run in `Dev Mode`, and another set of functionality when run in Figma design:
51   * ```ts title="Code sample to determine editorType and mode"
52   * if (figma.editorType === "dev") {
53   *   // Read the document and listen to API events
54   *   if (figma.mode === "inspect") {
55   *     // Running in inspect panel mode
56   *   } else if (figma.mode === "codegen") {
57   *     // Running in codegen mode
58   *   }
59   * } else if (figma.editorType === "figma") {
60   *   // If the plugin is run in Figma design, edit the document
61   *   if (figma.mode === 'textreview') {
62   *     // Running in text review mode
63   *   }
64   * } else if (figma.editorType === "figjam") {
65   *   // Do FigJam only operations
66   *   if (figma.mode === 'textreview') {
67   *     // Running in text review mode
68   *   }
69   * }
70   * ```
71   */
72  readonly mode: 'default' | 'textreview' | 'inspect' | 'codegen' | 'linkpreview' | 'auth'
73  /**
74   * The value specified in the `manifest.json` "id" field. This only exists for Plugins.
75   */
76  readonly pluginId?: string
77  /**
78   * Similar to `figma.pluginId` but for widgets. The value specified in the `manifest.json` "id" field. This only exists for Widgets.
79   */
80  readonly widgetId?: string
81  /**
82   * The file key of the current file this plugin is running on.
83   * **Only [private plugins](https://help.figma.com/hc/en-us/articles/4404228629655-Create-private-organization-plugins) and Figma-owned resources (such as the Jira and Asana widgets) have access to this.**
84   * To enable this behavior, you need to specify `enablePrivatePluginApi` in your `manifest.json`.
85   */
86  readonly fileKey: string | undefined
87  /**
88   * When enabled, causes all node properties and methods to skip over invisible nodes (and their descendants) inside {@link InstanceNode | instances}.
89   * This makes operations like document traversal much faster.
90   *
91   * Note: Defaults to true in Figma Dev Mode and false in Figma and FigJam
92   *
93   * @remarks
94   *
95   * Accessing and modifying invisible nodes and their descendants inside instances can be slow with the plugin API.
96   * This is especially true in large documents with tens of thousands of nodes where a call to {@link ChildrenMixin.findAll} might come across many of these invisible instance children.
97   *
98   * If your plugin does not need access to these nodes, we recommend setting `figma.skipInvisibleInstanceChildren = true` as that often makes document traversal significantly faster.
99   *
100   * When this flag is enabled, it will not be possible to access invisible nodes (and their descendants) inside instances. This has the following effects:
101   *
102   * - {@link ChildrenMixin.children} and methods such as {@link ChildrenMixin.findAll} will exclude these nodes.
103   * - {@link PluginAPI.getNodeByIdAsync} will return a promise containing null.
104   * - {@link PluginAPI.getNodeById} will return null.
105   * - Accessing a property on an existing node object for an invisible node will throw an error.
106   *
107   * For example, suppose that a portion of the document tree looks like this:
108   *
109   * Frame (visible) → Instance (visible) → Frame (invisible) → Text (visible)
110   *
111   * The last two frame and text nodes cannot be accessed after setting `figma.skipInvisibleInstanceChildren = true`.
112   *
113   * The benefit of enabling this flag is that document traversal methods, {@link ChildrenMixin.findAll} and {@link ChildrenMixin.findOne}, can be up to several times faster in large documents that have invisible instance children.
114   * {@link ChildrenMixin.findAllWithCriteria} can be up to hundreds of times faster in large documents.
115   */
116  skipInvisibleInstanceChildren: boolean
117  /**
118   * Note: This API is only available in FigJam
119   *
120   * This property contains methods used to read, set, and modify the built in FigJam timer.
121   *
122   * Read more in the [timer section](https://developers.figma.com/docs/plugins/api/figma-timer).
123   */
124  readonly timer?: TimerAPI
125  /**
126   * This property contains methods used to read and set the viewport, the user-visible area of the current page.
127   *
128   * Read more in the [viewport section](https://developers.figma.com/docs/plugins/api/figma-viewport).
129   */
130  readonly viewport: ViewportAPI
131  /**
132   * Note: `currentuser` must be specified in the permissions array in `manifest.json` to access this property.
133   *
134   * This property contains details about the current user.
135   */
136  readonly currentUser: User | null
137  /**
138   * Note: This API is only available in FigJam.
139   *
140   * `activeusers` must be specified in the permissions array in `manifest.json` to access this property.
141   *
142   * This property contains details about the active users in the file. `figma.activeUsers[0]` will match `figma.currentUser` for the `id`, `name`, `photoUrl`, `color`, and `sessionId` properties.
143   */
144  readonly activeUsers: ActiveUser[]
145  /**
146   * Note: `textreview` must be specified in the capabilities array in `manifest.json` to access this property.
147   *
148   * This property contains methods that enable text review features in your plugin.
149   */
150  readonly textreview?: TextReviewAPI
151  /**
152   * This property contains methods used to integrate with the Dev Mode codegen functionality.
153   *
154   * Read more in the [codegen section](https://developers.figma.com/docs/plugins/api/figma-codegen).
155   */
156  readonly codegen: CodegenAPI
157  /**
158   * This property contains methods used to integrate with the Figma for VS Code extension. If `undefined`, the plugin is not running in VS Code.
159   *
160   * Read more in [Dev Mode plugins in Visual Studio Code](https://developers.figma.com/docs/plugins/working-in-dev-mode#dev-mode-plugins-in-visual-studio-code)
161   */
162  readonly vscode?: VSCodeAPI
163  /**
164   * Caution: This is a private API only available to [Figma partners](https://www.figma.com/partners/)
165   */
166  readonly devResources?: DevResourcesAPI
167  /**
168   * Note: `payments` must be specified in the permissions array in `manifest.json` to access this property.
169   *
170   * This property contains methods for plugins that require payment.
171   */
172  readonly payments?: PaymentsAPI
173  /**
174   * Closes the plugin. You should always call this function once your plugin is done running. When called, any UI that's open will be closed and any `setTimeout` or `setInterval` timers will be cancelled.
175   *
176   * @param message - Optional -- display a visual bell toast with the message after the plugin closes.
177   *
178   * @remarks
179   *
180   * Calling `figma.closePlugin()` disables callbacks and Figma APIs. It does not, however, abort the plugin. Any lines of Javascript after this call will also run. For example, consider the following plugin that expects the user to have one layer selected:
181   *
182   * ```ts title="Simple closePlugin"
183   * if (figma.currentPage.selection.length !== 1) {
184   *   figma.closePlugin()
185   * }
186   * figma.currentPage.selection[0].opacity = 0.5
187   * ```
188   *
189   * This will not work. The last line will still run, but will throw an exception because access to `figma.currentPage` has been disabled. As such, it is not recommended to run any code after calling `figma.closePlugin()`.
190   *
191   * A simple way to easily exit your plugin is to wrap your plugin in a function, instead of running code at the top-level, and always follow `figma.closePlugin()` with a `return` statement:
192   *
193   * ```ts title="Early return"
194   * function main() {
195   *   if (figma.currentPage.selection.length !== 1) {
196   *     figma.closePlugin()
197   *     return
198   *   }
199   *   figma.currentPage.selection[0].opacity = 0.5
200   * }
201   * main()
202   * ```
203   *
204   * It's good practice to have all input validation done at the start of the plugin. However, there may be cases where the plugin may need to close after a chain of multiple function calls. If you expect to have to close the plugin deep within your code, but don't want to necessarily want the user to see an error, the example above will not be sufficient.
205   *
206   * One alternative is to use a top-level try-catch statement. However, you will need to be responsible for making sure that there are no usages of try-catch between the top-level try-catch and the call to `figma.closePlugin()`, or to pass along the close command if necessary. Example:
207   *
208   * ```ts title="Top-level try-catch"
209   * const CLOSE_PLUGIN_MSG = "_CLOSE_PLUGIN_"
210   * function someNestedFunctionCallThatClosesThePlugin() {
211   *   throw CLOSE_PLUGIN_MSG
212   * }
213   *
214   * function main() {
215   *   someNestedFunctionCallThatClosesThePlugin()
216   * }
217   *
218   * try {
219   *   main()
220   * } catch (e) {
221   *   if (e === CLOSE_PLUGIN_MSG) {
222   *     figma.closePlugin()
223   *   } else {
224   *     // >> DO NOT LEAVE THIS OUT <<
225   *     // If we caught any other kind of exception,
226   *     // it's a real error and should be passed along.
227   *     throw e
228   *   }
229   * }
230   * ```
231   */
232  closePlugin(message?: string): void
233  /**
234   * Shows a notification on the bottom of the screen.
235   *
236   * @param message - The message to show. It is limited to 100 characters. Longer messages will be truncated.
237   * @param options - An optional argument with the following optional parameters:
238   *
239   * ```ts
240   * interface NotificationOptions {
241   *   timeout?: number;
242   *   error?: boolean;
243   *   onDequeue?: (reason: NotifyDequeueReason) => void
244   *   button?: {
245   *     text: string
246   *     action: () => boolean | void
247   *   }
248   * }
249   * ```
250   *
251   * - `timeout`: How long the notification stays up in milliseconds before closing. Defaults to 3 seconds when not specified. Set the timeout to `Infinity` to make the notification show indefinitely until the plugin is closed.
252   * - `error`: If true, display the notification as an error message, with a different color.
253   * - `onDequeue`: A function that will run when the notification is dequeued. This can happen due to the timeout being reached, the notification being dismissed by the user or Figma, or the user clicking the notification's `button`.
254   *   - The function is passed a `NotifyDequeueReason`, which is defined as the following:
255   * ```ts
256   *  type NotifyDequeueReason = 'timeout' | 'dismiss' | 'action_button_click'
257   *  ```
258   * - `button`: An object representing an action button that will be added to the notification.
259   *    - `text`: The message to display on the action button.
260   *    - `action`: The function to execute when the user clicks the button. If this function returns `false`, the message will remain when the button is clicked. Otherwise, clicking the action button dismisses the notify message.
261   *
262   * @remarks
263   *
264   * The `notify` API is a convenient way to show a message to the user. These messages can be queued.
265   *
266   * If the message includes a custom action button, it will be closed automatically when the plugin closes.
267   *
268   * Calling `figma.notify` returns a `NotificationHandler` object. This object contains a single `handler.cancel()` method that can be used to remove the notification before it times out by itself. This is useful if the notification becomes no longer relevant.
269   *
270   * ```ts
271   * interface NotificationHandler {
272   *   cancel: () => void
273   * }
274   * ```
275   *
276   * An alternative way to show a message to the user is to pass a message to the {@link PluginAPI.closePlugin} function.
277   */
278  notify(message: string, options?: NotificationOptions): NotificationHandler
279  /**
280   * Commits actions to undo history. This does not trigger an undo.
281   *
282   * @remarks
283   *
284   * By default, plugin actions are not committed to undo history. Call `figma.commitUndo()` so that triggered
285   * undos can revert a subset of plugin actions.
286   *
287   * For example, after running the following plugin code, the first triggered undo will undo both the rectangle and the ellipse:
288   * ```ts
289   * figma.createRectangle();
290   * figma.createEllipse();
291   * figma.closePlugin();
292   * ```
293   * Whereas if we call `commitUndo()` in our plugin, the first triggered undo will only undo the ellipse:
294   * ```ts
295   * figma.createRectangle();
296   * figma.commitUndo();
297   * figma.createEllipse();
298   * figma.closePlugin();
299   * ```
300   */
301  commitUndo(): void
302  /**
303   * Triggers an undo action. Reverts to the last `commitUndo()` state.
304   */
305  triggerUndo(): void
306  /**
307   * Saves a new version of the file and adds it to the version history of the file. Returns the new version id.
308   * @param title - The title of the version. This must be a non-empty string.
309   * @param description - An optional argument to describe the version.
310   *
311   * Calling `saveVersionHistoryAsync` returns a promise that resolves to `null` or an instance of `VersionHistoryResult`:
312   *
313   * ```ts
314   * interface VersionHistoryResult {
315   *   id: string
316   * }
317   * ```
318   *
319   * - `id`: The version id of this newly saved version.
320   *
321   * @remarks
322   *
323   * It is not guaranteed that all changes made before this method is used will be saved to version history.
324   * For example,
325   *  ```ts title="Changes may not all be saved"
326   *  async function example() {
327   *    await figma.createRectangle();
328   *    await figma.saveVersionHistoryAsync('v1');
329   *    figma.closePlugin();
330   *  }
331   *  example().catch((e) => figma.closePluginWithFailure(e))
332   *  ```
333   * The newly created rectangle may not be included in the v1 version. As a work around, you can wait before calling `saveVersionHistoryAsync()`. For example,
334   *  ```ts title="Wait to save"
335   *  async function example() {
336   *    await figma.createRectangle();
337   *    await new Promise(r => setTimeout(r, 1000)); // wait for 1 second
338   *    await figma.saveVersionHistoryAsync('v1');
339   *    figma.closePlugin();
340   *  }
341   * ```
342   * Typically, manual chang