Plans to extract the API client lib (from `pkg/client`) into its own repository?

[andygrunwald]

Are there any plans to extract the Paperless Go Client lib (living in pkg/client) into its own repository?

This would have a couple of benefits:

• Discovery: When someone (like me) is looking for a Go client lib for Paperless, right now, it is not easy to find that the paperhooks repository has it as a sub-package. While this being an own repository, It would be easier to find (primarily via Google)
• Increased contribution/docs: Additional discovery may lead to increased contribution and its own documentation
• Independent development and release cycles: While the API of paperless evolves, the client lib evolves. Such feature development may not touch the webhook functionality of paperless (what paperhooks is mostly covering) - A new client endpoint in the client lib would require a new release without having additional features for paperhooks itself
• Dependency management: While other implementations (e.g. https://github.com/hansmi/prometheus-paperless-exporter) may require only the client lib and not the paperhooks functionality, a full dependency/download is required (with all its downsides of having dependencies and non used code)

Switching it would also have a couple of downsides:

• Additional development step: While you (@hansmi) maintain paperhooks, the paperless exporter and the client lib, an additional development step and additional maintenance overhead
• Breaking change: Folks who are importing pkg/client already may suffer from a breaking change -- This might be Okayish if you raise the major version for this change

Both lists may not be complete, just first thoughts from my side.

What do you think about this?

[hansmi]

The hook-related code is relatively minor by now. I started in that area, then needed a client and for simplicity also added the flag-related code (primarily kpflag). The name stuck.

The Go documentation page finds no public importing packages besides my own (https://pkg.go.dev/github.com/hansmi/paperhooks@v0.0.12/pkg/client?tab=importedby). I'm saying public because I personally have private code using the client and others may too. The effort for an extraction is not too bad, but is it worth it?

Overall I wouldn't mind extracting the API and flag-related code into a separate repository. It would be worth talking to the paperless-ngx project maintainers (@shamoon, @stumpylog, et al) to see if they'd be happy with a Go client repository within the project.

[shamoon]

Sorry, and I mean this with pure curiosity (no snark or whatever as can be sometimes the assumption on the web), but why would we house the client over there? We don’t currently maintain any of the third party clients and I don’t think either of us (obviously I don’t speak for stumpylog) are looking for more work to take on :)

[hansmi]

@shamoon, there's no requirement, technical or otherwise, to house the Go client within the paperless-ngx project. My thinking was that if the package name changes from github.com/hansmi/paperhooks/pkg/client to something else, requiring changes for downstream consumers anyway, moving to non-personal location could be considered. Obviously it can also remain in a personal namespace or a separate project.

[andygrunwald]

Thanks for the feedback @hansmi. Much appreciated.

The Go documentation page finds no public importing packages besides my own [...]

The reason for this could also be that it is hard to find the client code (aka other people don't know that those exist). But this is an assumption. I found it by accident / random.

We don’t currently maintain any of the third party clients and I don’t think either of us (obviously I don’t speak for stumpylog) are looking for more work to take on :)

An alternative option would be to create a paperless-go repo inside the paperless-ngx org and provide repository ownership to the community (e.g. @hansmi). However, this is 100% optional, as this is a project decision if 3rd party clients are "close" to the project or 100% left to the community (like this one here). I think both ways are totally fine, it is just a decision.

@hansmi In the end, it was a suggestion/question from my side. I think having it in its own repository with only the client code has multiple advantages. I also can understand why someone, as an open-source maintainer, wants things close and with less work.

I leave this decision to you :)
Let me know if I can support / help somehow.

[hansmi]

@shamoon, I'm sorry for pinging you once more. Did I understand you correctly that you'd rather not have client libraries within the overarching paperless-ngx namespace, even as separate repositories under community management?

[shamoon]

That would be my preference, yes.

[hansmi]

@andygrunwald, I'm fine with moving the client code to a separate repository eventually. I'll have to find time to set it up properly. The current setup works, so it's not urgent.

[andygrunwald]

That is fine. Take your time. Let me know if help is needed.