60 lines
2.8 KiB
Markdown
60 lines
2.8 KiB
Markdown
# go-nc-exapp
|
|
|
|
Shared Go library for Nextcloud ExApp Services: AppAPI authentication, OCS JSON calls, per-user ExApp preferences, Notifications, Users and Groups, an optional Required Groups Access Gate, an optional App navigation shell, and a Dialog.
|
|
|
|
Import: `gitea.neitzel.de/konrad/go-nc-exapp` (package `gonexapp`).
|
|
|
|
```bash
|
|
go get gitea.neitzel.de/konrad/go-nc-exapp
|
|
```
|
|
|
|
- [Guide](docs/guide.md) — how to call each capability
|
|
- [API](docs/api.md) — every exported symbol
|
|
- [Domain language](CONTEXT.md)
|
|
|
|
## Included
|
|
|
|
- [Credentials](docs/guide.md#credentials) — Nextcloud base URL, AppAPI secret, and requesting user
|
|
- [AuthHeaders](docs/guide.md#authheaders) — outbound AppAPI authorization
|
|
- [WithUser](docs/guide.md#withuser) — credentials scoped to one user
|
|
- [UserFromRequest](docs/guide.md#userfromrequest) — requesting user on an inbound request
|
|
- [OCSClient](docs/guide.md#ocsclient) — authenticated OCS calls with `format=json`
|
|
- [AppAPIPreferences](docs/guide.md#appapipreferences) — one string preference for the requesting user
|
|
- [AppAPINotifications](docs/guide.md#appapinotifications) — one bell notification
|
|
- [Groups](docs/guide.md#groups) — user groups, group members, and the group list
|
|
- [Access Gate](docs/guide.md#access-gate) — optional Required Groups check
|
|
- [Top Menu visibility](docs/guide.md#top-menu-visibility) — `TOP_MENU_ADMIN_REQUIRED`
|
|
- [App navigation](docs/guide.md#app-navigation) — optional Files-style shell
|
|
- [Dialog](docs/guide.md#dialog) — message, confirm, and prompt
|
|
|
|
## Excluded
|
|
|
|
- ExApp lifecycle HTTP routes (`/heartbeat`, `/enabled`, and `/init`). The Access Gate skips these by default and does not implement them
|
|
- HaRP listen, `serve()`, and unix-socket bootstrap
|
|
- Top-menu, script, and iframe UI registration
|
|
- WebDAV and file storage (see **go-nc-files**)
|
|
- Visit folder resolution (see **go-nc-files**)
|
|
- Fan-out notifications (`SendToGroup`, `SendToAdmins`)
|
|
- A library default admin user for directory OCS (callers pass that user with `WithUser`)
|
|
|
|
## Testing
|
|
|
|
Unit tests use `httptest` fake OCS servers. No live Nextcloud is required.
|
|
|
|
`go test ./...` fails when [`docs/api.md`](docs/api.md) does not match the exported API. Regenerate it with:
|
|
|
|
```bash
|
|
UPDATE_API_DOCS=1 go test -run TestAPIDoc -count=1
|
|
```
|
|
|
|
Runnable package examples: `go test -run Example`.
|
|
|
|
## Related
|
|
|
|
- **go-nc-files** — WebDAV, Working Folder, Saved Default, Visit resolution
|
|
- Workspace ADR 0013 — extraction from CheckDNS
|
|
- Workspace ADR `docs/adr/go-nc-exapp/0001-required-groups-access-gate.md` — Access Gate
|
|
- Workspace ADR `docs/adr/go-nc-exapp/0002-users-and-groups-as-requesting-user.md` — directory OCS as the requesting user
|
|
- Workspace ADR `docs/adr/go-nc-exapp/0003-app-navigation-shell.md` — App navigation shell
|
|
- Workspace ADR `docs/adr/go-nc-exapp/0004-dialog-in-exapp-page.md` — Dialog
|