Some objectives include:
Native TypeScript, transpiled to a node package.
ESM first (CommonJS is going the way of the dodo).
exceptions for http errors, graphql api errors, proprietary monday.com errors (including possibly error normalization since what comes from monday is erratic)
Built in retry for complexity limits.
Built in retry for socket resets, etc.
methods for all mutations, including typed & parsed responses.
methods for common queries, including typed & parsed outputs, built in pagination.
utility methods for creating JSON values for column mutations
utility methods for converting indexes to labels and vice versa.
If there are going to be multiple languages, ideally we’d coordinate so that we can have the same method names, interfaces, and patterns (within the norms of each language of course.) But this may not be possible.
My primary hope is to have something where we can manipulate monday objects without thinking about the underlying queries at all. (though still provide the ability to perform an arbitrary query of course.).
@Matias.Monday I think one of the best ways monday.com can contribute to this effort would be providing typing for the following JSON string payloads. These are currently only partially documented publicly as well.
board.column.settings_str (preferably by column type)
Additionally typing for columnValue trigger outputs (for the various column types) would be helpful.
I think these are safe contributions because they don’t provide any confidential information, and are part API responses/event payloads. But the hope being much of this is already document and could be shared for the benefit of the developer community.
Amazing to see this kind of initiative in our community! If y’all have a kickoff call, would love to be invited to it
As for types – I wanted to ask you about this. The reason we haven’t documented all the variations of settings_str and additional_info is because the structure may change. We try not to change them because we know it’s a breaking change, but we can’t guarantee it.
As far as settings_str & additional_info, I know they may experience breaking changes. But to me thats all the more reason to document them, and update that documentation when they are going to change. Ideally there would be a notification in a change log of an upcoming change.
We can test the object to see if its the new structure or old structure (code in advance) and then code for both until a breaking change goes live. Then our apps won’t have any downtime.
One example of a setting_str that we have to rely on is that of dropdowns. Its the only way to get a list of the labels and their corresponding indexes, the value contains the indexes only and additional_info should (but doesnt) contain the labels.
We do have a certain approach to our documentation. Having said that, we do take into account your thoughts and feedback about it. We will discuss this further internally. Not sure if this will change, but just wanted to let you know that it will be discussed.