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

```go
const DefaultCacheSeconds = 60
```

DefaultCacheSeconds is used when REQUIRED\_GROUPS\_CACHE\_SECONDS is unset or invalid.

### DefaultTopMenuAdminRequired

```go
const DefaultTopMenuAdminRequired = true
```

DefaultTopMenuAdminRequired is used when TOP\_MENU\_ADMIN\_REQUIRED is unset or invalid.

### EnvRequiredGroups

```go
const EnvRequiredGroups = "REQUIRED_GROUPS"
```

EnvRequiredGroups is the conventional deploy env name for Required Groups.

### EnvRequiredGroupsCacheSeconds

```go
const EnvRequiredGroupsCacheSeconds = "REQUIRED_GROUPS_CACHE_SECONDS"
```

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

### EnvTopMenuAdminRequired

```go
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

```go
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

```go
func DialogHTML() template.HTML
```

DialogHTML is the Dialog markup and script for an ExApp page, in English. App navigation includes the same fragment in the UI language and does not take a language argument. A page the ExApp renders itself inserts this fragment, or Credentials.DialogHTML when that page has a request. The page then calls exappDialog.message, exappDialog.confirm, or exappDialog.prompt and waits for the user's choice.

### FillScript

```go
func FillScript() template.HTML
```

FillScript replaces English source after load and refreshes Fold from the visible item name. It does not parse Phrase text as HTML. App navigation includes it. A page the ExApp renders itself places Script in the head and FillScript at the end of the body.

### ParseCacheSeconds

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

ParseCacheSeconds parses REQUIRED\_GROUPS\_CACHE\_SECONDS. Unset or invalid → defaultSec seconds; "0" → no cache.

### ParseRequiredGroups

```go
func ParseRequiredGroups(s string) []string
```

ParseRequiredGroups splits a comma-separated Required Groups env value.

### ResolveRequiredGroups

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

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

### TopMenuAdminRequired

```go
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

```go
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

```go
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

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

Check reports whether r may proceed under Required Groups.

#### AccessGate.Wrap

```go
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

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

AppAPINotifications creates Notifications via AppAPI OCS.

#### NewAppAPINotifications

```go
func NewAppAPINotifications(cred Credentials) AppAPINotifications
```

NewAppAPINotifications returns a sender using cred for AppAPI auth.

#### AppAPINotifications.Send

```go
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

```go
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

```go
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

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

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

#### AppAPIPreferences.Get

```go
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

```go
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

```go
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
	// Cred reads the UI language for this page from Nextcloud.
	// The zero value leaves the page in English.
	// The caller does not pass a language.
	Cred	Credentials
	// Phrases is the ExApp's set. The page script receives it.
	// Library chrome is not included. The zero value leaves the page in English.
	Phrases	Phrases
	// MissingPhrase names the ExApp Phrase for MissingMessage.
	MissingPhrase	string
}
```

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

```go
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

```go
type CheckResult int
```

CheckResult is the outcome of AccessGate.Check.

#### CheckAllowed

#### CheckDenied

#### CheckUnauthorized

#### CheckUnavailable

```go
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

```go
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

```go
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.DialogHTML

```go
func (c Credentials) DialogHTML(r *http.Request) template.HTML
```

DialogHTML is the Dialog fragment in the UI language of r. A missing Requesting user or a failed read uses English. The caller does not pass a language.

#### Credentials.UILanguage

```go
func (c Credentials) UILanguage(r *http.Request) string
```

UILanguage is the language of the Phrases for this request, "en" or "de". It reads the Requesting user's language from the Provisioning OCS user record and forwards the request's Accept-Language on that read. The locale field is ignored. A more specific code uses the broader language when this Library provides that language. Any other code, a missing Requesting user, or a failed read is English, and the page still renders. A second call with the request returned from a page render reuses that result.

#### Credentials.WithUser

```go
func (c Credentials) WithUser(userID string) Credentials
```

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

### Groups

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

Groups reads Users and Groups from Provisioning OCS.

#### NewGroups

```go
func NewGroups(cred Credentials) Groups
```

NewGroups returns a directory reader using cred for AppAPI auth.

#### Groups.GroupMembers

```go
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

```go
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

```go
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

```go
type Item struct {
	ID		string
	Label		string
	Icon		string
	Phrase		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. Phrase names the ExApp Phrase for Label. The English label stays in the page until the script replaces it. Empty leaves the label as written.

### Notification

```go
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

```go
type OCSClient struct {
	Cred	Credentials
	Client	*http.Client
	Header	http.Header
}
```

OCSClient performs AppAPI-authenticated OCS requests with format=json. Header is copied onto the outbound request after the AppAPI auth headers. The UI language read uses it to forward Accept-Language.

#### OCSClient.Call

```go
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

```go
func (c OCSClient) URL(path string) string
```

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

### Phrases

```go
type Phrases struct {
	// contains filtered or unexported fields
}
```

Phrases is one ExApp's merged Phrase set. English is the complete set. A module set is merged with Merge; a repeated id uses the set added later. The page script receives this set. Library chrome is not included.

#### Merge

```go
func Merge(sets ...Phrases) Phrases
```

Merge returns the sets combined in order. A repeated id uses the text from the set added later.

#### ParsePhrases

```go
func ParsePhrases(en, de []byte) (Phrases, error)
```

ParsePhrases reads an English object and a German object.

#### PhrasesFromFS

```go
func PhrasesFromFS(fsys fs.FS) (Phrases, error)
```

PhrasesFromFS reads i18n/en.json and i18n/de.json. Each file is one JSON object of id → text.

#### Phrases.Script

```go
func (p Phrases) Script(lang string) template.HTML
```

Script defines exappPhrase for the page, from this set only.

#### Phrases.Sentence

```go
func (p Phrases) Sentence(lang, id string, holes map[string]string) string
```

Sentence is the finished text for lang. A missing text for that language uses the English text. An id missing from English is the id. A hole with no value stays visible as {name}. The result is plain text; the caller escapes it when writing HTML.