go-nc-exapp/README.md

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).

go get gitea.neitzel.de/konrad/go-nc-exapp

• Guide — how to call each capability
• API — every exported symbol
• Domain language

Included

• Credentials — Nextcloud base URL, AppAPI secret, and requesting user
• AuthHeaders — outbound AppAPI authorization
• WithUser — credentials scoped to one user
• UserFromRequest — requesting user on an inbound request
• OCSClient — authenticated OCS calls with format=json
• AppAPIPreferences — one string preference for the requesting user
• AppAPINotifications — one bell notification
• Groups — user groups, group members, and the group list
• Access Gate — optional Required Groups check
• Top Menu visibility — TOP_MENU_ADMIN_REQUIRED
• App navigation — optional Files-style shell
• 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 does not match the exported API. Regenerate it with:

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