Confusing and missing API docs?

[sbrl]

Hello,

I'm currently using this package in a project, but it is proving to be a difficult task as the docs available are rather limited.

The README does not contain any obvious links to documentation, and while I can search the codebase on how to use e.g. sftp.write(), all I can find is https://github.com/NobleMajo/hivessh/blob/main/src/essentials/SftpPromiseWrapper.ts#L136 and https://github.com/NobleMajo/hivessh/blob/main/src/essentials/SftpPromiseWrapper.ts#L400.

In the README, I see the following: https://github.com/NobleMajo/hivessh/#technologies

.....but it is not immediately obvious that the API for hivessh is the same or different to that of the ssh2 package.

The ssh2 package docs suggest that all SFTP methods are uppercase: https://github.com/mscdex/ssh2/blob/master/SFTP.md

....but that is not the case in hivessh (SSHHost.sftp), and there is not a link to the above, nor an explanation of the differences between hivessh and ssh2's implementation thereof. If method names have changed, have e.g. arguments etc changed too? The only way to tell is to go digging around in hivessh's code, which is not a helpful or time-efficient solution.

To this end, I suggest having a section that:

a) Links to the relevant docs, even if they are from another package
b) Explains the relationship between the other packages and hivessh
c) Outlines and details the differences between hivessh and the other package.

It would be nice to have some docs on how to use sftp if possible as it is not obvious from the above how to use it (especially for e.g. writing to disk), but I understand this would be more effort than the above.

[github-actions]

👋 Hello!

Welcome to the repository, and thank you for opening an issue. 🎉 We're excited to have you contribute! Please make sure to include all the relevant details to help us understand your report or suggestion.

If you’re new here, take a moment to review our contribution guidelines and code of conduct. These documents will help you collaborate effectively and ensure a positive experience for everyone.

We're here to help—feel free to reach out if you have any questions. 🚀

Thank you, and happy coding! 💻

[sbrl]

Hey, @github-actions! Thanks for the links. However, they do not appear to work for me, as they link to a search of the issues list.

/cc @NobleMajo as the owner of this repo: I think the bot is broken.

Also, what do you mean by feel free to reach out if you have any questions? Is a GitHub issue not considered reaching out, or is there another preferred method to use here? From this I am unclear on the protocol you expect people to follow.

[NobleMajo]

Hii,
i will check the issue later.

But i think its already a good idea to create a ssh2 and hivessh comparison.

THX sbrl

[NobleMajo]

Hii @sbrl,
as for the documentation, i hope my recent changes have cleared up some misunderstandings and made it more obvious that the core functions are a wrap around of the ssh2-library.
https://github.com/NobleMajo/hivessh
If you sill find some potential risks for misunderstanding, please let me know where and why.

As for the sftp functions, i wrapped the ssh2-library with a promise-based approche.
Shy the ssh2-library documents a few functions in uppercase I don't quite understand either, but in javascript (or generally in the c-influenced code world) you can assume camel case for function names (if a language doesn't define anything specific, like golang).
I have used the typescript types and interfaces of the ssh2-library, which explicitly and understandably use lowercase and i have adapted them for promises, so yes the callback parameters and return values have changed.

I hope that the following types will help you: https://www.npmjs.com/package/hivessh/file/fd0e59bb46b481ba4758921a292de6d5ef3437ec849a896f673ab91f6f8059da
(Or here at /dist/essentials/SftpPromiseWrapper.d.ts)

I'll check where i can add the link above in the readme together with: https://github.com/mscdex/ssh2/blob/master/SFTP.md

The actions bot greet message is now changed, thanks for pointing out the problems and misunderstandings with the bot.
In the future I'll also add some information about the protocol I expect people to follow, but I think in the end I'll just tell people to relax and wait for a response.

I appreciate your effort and look forward to collaborating with you! 🚀
Cheers ❤️