I’m inquiring for interest in starting a community developed sdk in typescript intended for nodejs use. (as the current javascript sdk provides about zero additional value on the server-side beside being a wrapper for node-fetch)
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.
I am open to being a maintainer, but admit that I’m not experienced in maintaining public projects, so those with more experience would be more than welcome!
Right now I’m trying to gauge interest in others contributing, as I don’t see a point going through the effort of maintaining it publicly if there isn’t any interest in others contributing.
Thoughts on the project? (lets refrain from deep discussion on features, and do that on github if there is enough interest to justify moving forward).
I’d really love to see community api sdks for multiple languages (TypeScript/JavaScript, PHP, Go, Python, .NET, Java, Ruby, maybe even Rust).
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)
item.colum_value.value
item.colum_value.additional_info
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.
Our current approach for documentation is (broadly): if it’s documented, then you can trust that it won’t change without upcoming notice. If it’s not documented, then it may change without notice.
The JSON structure/types of the fields settings_str and additional_info are examples of the latter – we’d need to consult with our dev team before documenting them.
As for adding support for upcoming changes to the SDK (old version OR new version) – amazing idea!
I’m a believer in the Wild West mentality when the current theory is to create documentation when it’s perfect. Is anything perfect or not in a state of change?
Schema is important. Does make creating types up to a point easy. But doesn’t cover the parsed structure of those JSON strings that are returned though. It only says its going to be a string.
Yup, if something can’t be documented until its not going to change, it means it only gets documented at end of life
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.
