go-nc-exapp/docs/api.md

API

Generated from the package comment and every exported declaration. Do not edit. Regenerate with UPDATE_API_DOCS=1 go test -run TestAPIDoc -count=1.

Package gonexapp

Package gonexapp provides AppAPI credentials, OCS JSON calls, ExApp user preferences, Notifications, Users and Groups reads, an optional Required Groups Access Gate, an optional App navigation shell, and a Dialog for Nextcloud ExApp Services.

Constants

DefaultCacheSeconds

const DefaultCacheSeconds = 60

DefaultCacheSeconds is used when REQUIRED_GROUPS_CACHE_SECONDS is unset or invalid.

DefaultTopMenuAdminRequired

const DefaultTopMenuAdminRequired = true

DefaultTopMenuAdminRequired is used when TOP_MENU_ADMIN_REQUIRED is unset or invalid.

EnvRequiredGroups

const EnvRequiredGroups = "REQUIRED_GROUPS"

EnvRequiredGroups is the conventional deploy env name for Required Groups.

EnvRequiredGroupsCacheSeconds

const EnvRequiredGroupsCacheSeconds = "REQUIRED_GROUPS_CACHE_SECONDS"

EnvRequiredGroupsCacheSeconds is the conventional deploy env name for Access Gate cache TTL.

EnvTopMenuAdminRequired

const EnvTopMenuAdminRequired = "TOP_MENU_ADMIN_REQUIRED"

EnvTopMenuAdminRequired is the conventional deploy env name for Top Menu visibility. Declare it in the ExApp info.xml environment-variables section.

Variables

NextcloudIcons

var NextcloudIcons = nextcloudIcons{
	Folder:			"/core/img/filetypes/folder.svg",
	FolderShared:		"/core/img/filetypes/folder-shared.svg",
	FolderPublic:		"/core/img/filetypes/folder-public.svg",
	FolderStarred:		"/core/img/filetypes/folder-starred.svg",
	FolderEncrypted:	"/core/img/filetypes/folder-encrypted.svg",
	File:			"/core/img/filetypes/file.svg",
	Text:			"/core/img/filetypes/text.svg",
	Image:			"/core/img/filetypes/image.svg",
	Audio:			"/core/img/filetypes/audio.svg",
	Video:			"/core/img/filetypes/video.svg",
	PDF:			"/core/img/filetypes/application-pdf.svg",
	Document:		"/core/img/filetypes/x-office-document.svg",
	Spreadsheet:		"/core/img/filetypes/x-office-spreadsheet.svg",
	Presentation:		"/core/img/filetypes/x-office-presentation.svg",
	Files:			"/core/img/places/files.svg",
	Home:			"/core/img/places/home.svg",
	Calendar:		"/core/img/places/calendar.svg",
	Contacts:		"/core/img/places/contacts.svg",
	Add:			"/core/img/actions/add.svg",
	Delete:			"/core/img/actions/delete.svg",
	Edit:			"/core/img/actions/edit.svg",
	Rename:			"/core/img/actions/rename.svg",
	Download:		"/core/img/actions/download.svg",
	Upload:			"/core/img/actions/upload.svg",
	Share:			"/core/img/actions/share.svg",
	Search:			"/core/img/actions/search.svg",
	Settings:		"/core/img/actions/settings.svg",
	Info:			"/core/img/actions/info.svg",
	History:		"/core/img/actions/history.svg",
	Password:		"/core/img/actions/password.svg",
	Confirm:		"/core/img/actions/confirm.svg",
	Close:			"/core/img/actions/close.svg",
	Star:			"/core/img/actions/star.svg",
	User:			"/core/img/actions/user.svg",
	Group:			"/core/img/actions/group.svg",
	Mail:			"/core/img/actions/mail.svg",
	Menu:			"/core/img/actions/menu.svg",
	External:		"/core/img/actions/external.svg",
	Filter:			"/core/img/actions/filter.svg",
	Recent:			"/core/img/actions/recent.svg",
	Tag:			"/core/img/actions/tag.svg",
}

NextcloudIcons are SVG paths served by Nextcloud core under /core/img/. The library does not ship the files. Set Item.Icon to one of these. Dark mode inverts them with Nextcloud’s --background-invert-if-dark filter.

Functions

DialogHTML

func DialogHTML() template.HTML

DialogHTML is the Dialog markup and script for an ExApp page. App navigation includes it. A page the ExApp renders itself inserts the same fragment. The page then calls exappDialog.message, exappDialog.confirm, or exappDialog.prompt and waits for the user's choice.

ParseCacheSeconds

func ParseCacheSeconds(s string, defaultSec int) time.Duration

ParseCacheSeconds parses REQUIRED_GROUPS_CACHE_SECONDS. Unset or invalid → defaultSec seconds; "0" → no cache.

ParseRequiredGroups

func ParseRequiredGroups(s string) []string

ParseRequiredGroups splits a comma-separated Required Groups env value.

ResolveRequiredGroups

func ResolveRequiredGroups(envValue string, envSet bool, codeDefault []string) []string

ResolveRequiredGroups applies env override rules: unset uses codeDefault; set (including empty) replaces the default.

TopMenuAdminRequired

func TopMenuAdminRequired(envValue string, defaultAdminRequired bool) string

TopMenuAdminRequired returns "1" or "0" for the AppAPI top-menu OCS adminRequired field. Only "0" and "1" are accepted; any other value falls back to defaultAdminRequired. An empty envValue means unset and also uses defaultAdminRequired.

UserFromRequest

func UserFromRequest(r *http.Request) (string, error)

UserFromRequest reads the requesting user from AUTHORIZATION-APP-API on an inbound ExApp request. It returns an error when the header is missing, is not base64, or contains no user id before the colon.

Types

AccessGate

type AccessGate struct {
	Cred		Credentials
	Groups		[]string
	CacheTTL	time.Duration	// 0 disables cache
	ExtraSkipPaths	[]string
	Client		*http.Client
	OCS		OCSClient
	Now		func() time.Time
	// contains filtered or unexported fields
}

AccessGate enforces Required Groups for the Requesting user on ExApp HTTP traffic.

AccessGate.Check

func (g *AccessGate) Check(r *http.Request) CheckResult

Check reports whether r may proceed under Required Groups.

AccessGate.Wrap

func (g AccessGate) Wrap(next http.Handler) http.Handler

Wrap returns a handler that runs Check before next. CheckAllowed calls next. CheckUnauthorized writes 401. CheckUnavailable writes 503. CheckDenied writes English HTML with status 200 and frame-ancestors 'self' when the request accepts text/html, and 403 otherwise. An empty Groups list allows every request. Paths /heartbeat, /enabled, /init, and /js/ are skipped, plus ExtraSkipPaths.

AppAPINotifications

type AppAPINotifications struct {
	Cred	Credentials
	Client	*http.Client
	OCS	OCSClient
}

AppAPINotifications creates Notifications via AppAPI OCS.

NewAppAPINotifications

func NewAppAPINotifications(cred Credentials) AppAPINotifications

NewAppAPINotifications returns a sender using cred for AppAPI auth.

AppAPINotifications.Send

func (n AppAPINotifications) Send(notif Notification) error

Send creates a Notification for Cred.UserID. It returns an error when UserID or Subject is empty, or when the OCS call fails. AppAPI notification OCS accepts Subject, Message, Link, and rich-object parameters. It does not accept actions or a custom icon.

AppAPINotifications.SendTo

func (n AppAPINotifications) SendTo(userID string, notif Notification) error

SendTo creates a Notification for userID. The OCS call is authenticated as that user via WithUser. It returns an error when userID or Subject is empty, or when the OCS call fails.

AppAPIPreferences

type AppAPIPreferences struct {
	Cred	Credentials
	AppID	string
	Key	string
	Client	*http.Client
	OCS	OCSClient
}

AppAPIPreferences reads and writes one string ExApp preference for the requesting user.

NewAppAPIPreferences

func NewAppAPIPreferences(cred Credentials, appID, key string) AppAPIPreferences

NewAppAPIPreferences returns a preference store for appID and key using cred for auth.

AppAPIPreferences.Get

func (p AppAPIPreferences) Get() (string, error)

Get loads the configured preference key for the requesting user. A missing key returns an empty string and a nil error. It returns an error when the OCS call fails or the body cannot be decoded.

AppAPIPreferences.Set

func (p AppAPIPreferences) Set(value string) error

Set stores value for the configured preference key. The value is stored as non-sensitive. It returns an error when the OCS call fails.

AppNavigation

type AppNavigation struct {
	Items		func(*http.Request) []Item
	Page		func(*http.Request, string) (string, bool)
	Header		func(*http.Request) string
	DefaultID	string
	MissingMessage	string
	SelectKey	string
	// Title is the document title. Empty means "App navigation".
	Title	string
	// DisableTheme skips the Nextcloud theme stylesheets. The zero value
	// loads the active theme.
	DisableTheme	bool
}

AppNavigation is the Files-style shell an ExApp mounts. Items, Page, and DefaultID are required. Header and MissingMessage are optional. SelectKey defaults to "item". Every other query parameter, including the Visit folder, is copied onto the corrected address. An ExApp that never calls Handler keeps its own page.

AppNavigation.Handler

func (n AppNavigation) Handler() http.Handler

Handler serves the shell. The selected item is the SelectKey query parameter. A missing item renders DefaultID, includes MissingMessage, and publishes the corrected query on data-address so the page can replace the address. Every parent starts expanded. Folding is client state for this document only.

CheckResult

type CheckResult int

CheckResult is the outcome of AccessGate.Check.

CheckAllowed

CheckDenied

CheckUnauthorized

CheckUnavailable

const (
	// CheckAllowed means the request may proceed (or the gate is inactive / skipped).
	CheckAllowed	CheckResult	= iota
	// CheckDenied means the Requesting user is not in Required Groups.
	CheckDenied
	// CheckUnauthorized means no Requesting user could be read from the request.
	CheckUnauthorized
	// CheckUnavailable means group membership could not be determined (e.g. OCS error).
	CheckUnavailable
)

Credentials

type Credentials struct {
	BaseURL		string
	AppID		string
	AppVersion	string
	AAVersion	string
	AppSecret	string
	UserID		string
}

Credentials are what an ExApp needs to call Nextcloud as one user. BaseURL is the Nextcloud instance URL. A trailing slash is tolerated by callers in this package and is removed when they build a URL. AppID, AppVersion, and AAVersion are sent as EX-APP-ID, EX-APP-VERSION, and AA-VERSION. AppSecret and UserID form the AUTHORIZATION-APP-API token.

Credentials.AuthHeaders

func (c Credentials) AuthHeaders() http.Header

AuthHeaders returns AppAPI headers for a request to Nextcloud. The set is AA-VERSION, EX-APP-ID, EX-APP-VERSION, AUTHORIZATION-APP-API, and OCS-APIRequest. AUTHORIZATION-APP-API is base64 of UserID, a colon, and AppSecret. The method does not return an error; empty fields are sent as empty.

Credentials.WithUser

func (c Credentials) WithUser(userID string) Credentials

WithUser returns a copy whose UserID is userID. The receiver is not modified.

Groups

type Groups struct {
	Cred	Credentials
	Client	*http.Client
	OCS	OCSClient
}

Groups reads Users and Groups from Provisioning OCS.

NewGroups

func NewGroups(cred Credentials) Groups

NewGroups returns a directory reader using cred for AppAPI auth.

Groups.GroupMembers

func (g Groups) GroupMembers(groupID string) ([]string, error)

GroupMembers returns the user ids in groupID. The OCS call uses Cred as-is. Nextcloud requires that user to be an admin or a subadmin of the group. It returns an error when the OCS call fails or the body cannot be decoded. There is no search or paging.

Groups.ListGroups

func (g Groups) ListGroups() ([]string, error)

ListGroups returns instance group ids. The OCS call uses Cred as-is and needs an admin or subadmin. It returns an error when the OCS call fails or the body cannot be decoded. There is no search or paging.

Groups.UserGroups

func (g Groups) UserGroups(userID string) ([]string, error)

UserGroups returns the Nextcloud group ids of userID. The OCS call is authenticated as userID. It returns an error when the OCS call fails or the body cannot be decoded.

Item

type Item struct {
	ID		string
	Label		string
	Icon		string
	Children	[]Item
}

Item is one App navigation entry. The ExApp chooses the ids and labels. Children may nest. The shell does not interpret the ids. Icon is an optional same-origin image URL. NextcloudIcons names the core SVGs.

Notification

type Notification struct {
	Subject		string
	Message		string
	Link		string
	SubjectParams	map[string]any
	MessageParams	map[string]any
}

Notification is one Nextcloud bell for a single Recipient.

OCSClient

type OCSClient struct {
	Cred	Credentials
	Client	*http.Client
}

OCSClient performs AppAPI-authenticated OCS requests with format=json.

OCSClient.Call

func (c OCSClient) Call(method, path string, body []byte) ([]byte, error)

Call performs method against path with an optional JSON body and returns the response body after verifying it is valid JSON. Non-2xx responses return an error including the status.

OCSClient.URL

func (c OCSClient) URL(path string) string

URL builds an OCS URL under /ocs/v2.php with format=json.