# 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