I hope someone form the community support could send this post for developers.

There are existing bugs that could break most plugins.

Bug 1 - The plugin api can't be used to modify fills if there is a pattern fill.

The following error message shows when setting the fill via `node.fills = fillsClone` :
`in set_fills: Property "fills" failed validation: Invalid discriminator value. Expected 'SOLID' | 'GRADIENT_LINEAR' | 'GRADIENT_RADIAL' | 'GRADIENT_ANGULAR' | 'GRADIENT_DIAMOND' | 'IMAGE' | 'VIDEO' at 3].type`

It seems that the validation of the internal `set_fills` is outdated, as it doesn't include the new type 'PATTERN'.

This will break any plugin that modifies fills if there is a pattern fill among fills.

Bug 2 - The plugin api can't be used to modify fills if there is a video fill.

Case 1 - Can't modify fills if there is an empty video fill (no video uploaded yet) :

According to the type definitions for video paint : https://www.figma.com/plugin-docs/api/Paint/#videopaint

The `videoHash` property can be null, when the video fill is empty, but when cloning `node.fills` and for example editing a solid fill, then assigning the clone via `node.fills = fillsClone`, the following error is thrown :
`in set_fills: Property "fills" failed validation: Expected string, received null at 2].videoHash`

Case 2 - Can't modify fills even if there is a video :

When trying `node.fills = fillsClone`, even if this clone is identical and no mutation was done on it, the following error is thrown : 
`in set_fills: Invalid SHA1 hash`

Case 3 - Can't modify fills because of validation error

Again, according to the type definitions for video paint, there is no `imageTransform` property in video paints, but in reality, they have this property!

When you log `node.fills` in the console, the property `imageTransform` is present in fill paints where type = `VIDEO`, and because of this, when you clone the node's fills, this property is included in the clone, and when you try to assign this clone via `node.fills = fillsClone`, the following error is thrown :
`in set_fills: Property "fills" failed validation: Unrecognized key(s) in object: 'imageTransform' at index 2`

Again it seems that the validation of the internal `set_fills` is outdated.

This will break any plugin that modifies fills if there is a video fill among fills.

Bug 3 -  Can't modify effects if there the node has noise or texture effects  :

According to the type definitions for effects : https://www.figma.com/plugin-docs/api/Effect/

The noise and texture effects doesn't have `boundVariables` property, yet when you add a noise or a texture effect to a node and look at `node.effects` in the console, you will find the `boundVariables` property present with a value of an empty object literal.

This doesn't just cause a typescript error while development, but it gives a runtime error similar to the errors seen in the bugs above, a validation error.

When you clone `node.effects` to do some modifications, the `boundVariables` will be present in the clone, but when you try `node.effects = effectsClone`, the following error is thrown :
`in set_effects: Property "effects" failed validation: Unrecognized key(s) in object: 'boundVariables' at index 0`

A current workaround, is to delete `boundVariables` form any noise and texture effects before assigning, but this is not reliable in production, if this `boundVariables` was added to these effect types later in an api update, the property deletion would cause a different error.

The solution is to either add `boundVariables` to noise and texture effects, or update the internal setter to accept it without throwing errors, or to go with the logical solution, and to not add `boundVariables` property with an empty object to the effect objects of noise and texture effects.

This bug will break any plugin that modifies effects if there is a noise or texture effect among effects.

Bug 4 - Error in the plugin typing

According to the type definition for `ComponentPropertyDefinitions` : https://www.figma.com/plugin-docs/api/ComponentPropertyDefinitions/

The `VariableBindableComponentPropertyDefinitionField` = "defaultValue"

Which means that when I'm working with a component node's bound variables, I should be able to write `node.componentPropertyDefinitions.boundVariable?.defaultValue`, but this would cause the type checker to complain because the plugin typings still define `boundVariables` as `{ Vfield in VariableBindableComponentPropertyField]?: VariableAlias; };`

Which is wrong, `VariableBindableComponentPropertyField` should be replaced with `VariableBindableComponentPropertyDefinitionField`

---------------

Limitations :

1 - `node.boundVariables` is a read only property that can only be set via `node.setBoundVariables`, no problem here, but the `boundVariables` property that is inside fill objects or effect objects and so on, is NOT read only, it's writable, which is excellent, when writing a function that goes through every node in the file to replace bound variables, it's much faster to mutate `boundVariables` in the fill / effect clone, for example `fillsClone0i].boundVariable = {...}`, than to use helper methods like `figma.variables.setBoundVariablesForPaint`. Mutating a property is faster than accessing `figma.variables` then calling a function, especially when working with thousand of nodes in a file.

But since the type definitions for `boundVariables` everywhere define it as read only, it causes some issues while developing, I suggest to remove the read only flag from `boundVariable` when it's not a direct property of the node, this will reflect its writable state, and will improve developer experience.

2 - the `boundVariables` property being marked as optional via `?` is causing a big friction. Everytime `boundVariables` is used, it must either be null checked or asserted to the compiler, and sometimes it's more than this when using it in complex code logic.

The optional mark was removed, then was brought back because of some developer complaints, but is it correct to mark a property as optional while it's not in reality? It's always present with an object whether it's empty or has variable aliases.

I suggest to remove this optional marker, and this should not be problem for any plugin that is no longer maintained, as it will keep using an older version of plugin typings where the optional marker is present, however, for plugins that are still maintained, their authors would need to update the code, and there is not to a lot update.

3 - The plugin api doesn't expose a property to get the max number of modes that can be added to a collection, this could be added to the global figma object, currently to get the number, it requires creating a temporary collection and adding modes until an error is thrown, and extracting the number from the error message. I'm suggesting the addition of such a property to the plugin api.