# 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 goncfiles

Package goncfiles provides a Nextcloud User Files seam (local and WebDAV), Saved Default path storage, and Visit-scoped Working Folder resolution for ExApp Services.

## Variables

### ErrNotExist

### ErrForbidden

### ErrNotDir

```go
var (
	// ErrNotExist means the folder or file is missing.
	// Callers should use IsNotExist rather than comparing text.
	ErrNotExist	= errors.New("not found")
	// ErrForbidden means the caller may not read or write the path.
	// Callers should use IsForbidden rather than comparing text.
	ErrForbidden	= errors.New("forbidden")
	// ErrNotDir means the path exists and is not a directory.
	ErrNotDir	= errors.New("not a directory")
)
```

## Functions

### CleanRel

```go
func CleanRel(rel string) string
```

CleanRel normalizes a User Files Root–relative path. The result is empty when rel is empty, contains "..", is a URL, or is a bare numeric Nextcloud file ID. An empty result is not a usable path. Backslashes are treated as slashes. A leading or trailing slash is removed.

### IsForbidden

```go
func IsForbidden(err error) bool
```

IsForbidden reports whether err wraps ErrForbidden.

### IsNotExist

```go
func IsNotExist(err error) bool
```

IsNotExist reports whether err wraps ErrNotExist.

### LocalPath

```go
func LocalPath(f Folder) (string, bool)
```

LocalPath returns the absolute directory when f is a local folder.

### RequireBasename

```go
func RequireBasename(name string) error
```

RequireBasename rejects path segments that are not a single basename.

## Types

### DefaultPathStore

```go
type DefaultPathStore interface {
	// GetDefault returns the stored path, or empty when none is set yet.
	GetDefault() (string, error)
	// SetDefault writes a User Files Root–relative Working Folder path.
	SetDefault(rel string) error
}
```

DefaultPathStore persists the Saved Default Working Folder path (User Files Root–relative).

### Entry

```go
type Entry struct {
	Name	string
	IsDir	bool
}
```

Entry is a first-level name in a Working Folder.

### FileStore

```go
type FileStore struct {
	Path string
}
```

FileStore is the local-adapter settings JSON file.

#### FileStore.GetDefault

```go
func (s FileStore) GetDefault() (string, error)
```

GetDefault reads the saved default; empty means the caller should use the product initial default.

#### FileStore.SetDefault

```go
func (s FileStore) SetDefault(rel string) error
```

SetDefault writes the saved Working Folder path.

### Folder

```go
type Folder interface {
	// List returns first-level names in the Working Folder.
	List() ([]Entry, error)
	// Read returns the contents of a basename in the Working Folder.
	Read(name string) ([]byte, error)
	// Write creates or replaces a basename in the Working Folder.
	Write(name string, data []byte) error
	// Exists reports whether name is a non-directory file in the Working Folder.
	Exists(name string) (bool, error)
	// Remove deletes a basename in the Working Folder.
	Remove(name string) error
}
```

Folder is flat storage for one Working Folder (basenames only).

#### LocalFolder

```go
func LocalFolder(dir string) Folder
```

LocalFolder returns a Folder backed by an absolute local directory.

### Local

```go
type Local struct {
	RootDir string
}
```

Local is a User Files Root on the local filesystem.

#### Local.EnsureFolder

```go
func (l Local) EnsureFolder(rel string) (Folder, error)
```

EnsureFolder creates the directory and its parents if missing, then opens it. It returns an error wrapping ErrForbidden when the process cannot create the directory, or a plain error when rel is not valid.

#### Local.OpenFolder

```go
func (l Local) OpenFolder(rel string) (Folder, error)
```

OpenFolder opens an existing directory under the local root. It returns an error wrapping ErrNotExist, ErrForbidden, or ErrNotDir, or a plain error when rel is not a valid User Files Root–relative path.

### Memory

```go
type Memory struct {
	Value string
}
```

Memory is an in-memory DefaultPathStore for tests.

#### Memory.GetDefault

```go
func (m *Memory) GetDefault() (string, error)
```

GetDefault returns the in-memory value.

#### Memory.SetDefault

```go
func (m *Memory) SetDefault(rel string) error
```

SetDefault stores the value in memory.

### Root

```go
type Root interface {
	// OpenFolder opens an existing folder at rel (User Files Root–relative).
	OpenFolder(rel string) (Folder, error)
	// EnsureFolder creates rel (and parents) if needed, then opens it.
	EnsureFolder(rel string) (Folder, error)
}
```

Root is User Files Root–relative folder access.

### Visit

```go
type Visit struct {
	SavedDefault	string
	WorkingRel	string
	VisitRelative	string
	FS		Folder
	// contains filtered or unexported fields
}
```

Visit is one ExApp opening: Working Folder for this request plus the Saved Default.

#### Open

```go
func Open(root Root, defaults DefaultPathStore, initialFolderName, visitRelative string) (*Visit, error)
```

Open resolves the Working Folder for this visit. initialFolderName is used when no Saved Default is stored yet (app-icon first launch). visitRelative empty means app-icon launch (Saved Default, creating the initial folder empty if missing). A Files-view folder is used only for this visit and does not change the Saved Default. Missing or forbidden visit paths fail closed (no create, no fallback).

#### OpenLocal

```go
func OpenLocal(filesRoot, settingsPath, initialFolderName, visitRelative string) (*Visit, error)
```

OpenLocal is the local-adapter convenience: files root + settings JSON.

#### Visit.SetDefault

```go
func (v *Visit) SetDefault(relative string) error
```

SetDefault persists a new Saved Default and ensures the folder exists.

#### Visit.WorkingDir

```go
func (v *Visit) WorkingDir() string
```

WorkingDir returns a local absolute path when using the local adapter; otherwise WorkingRel.

### WebDAVRoot

```go
type WebDAVRoot struct {
	Cred	gonexapp.Credentials
	Client	*http.Client
}
```

WebDAVRoot is a User Files Root at /remote.php/dav/files/{user}/. Cred supplies the user id and AppAPI auth headers. A nil Client uses http.DefaultClient.

#### WebDAVRoot.EnsureFolder

```go
func (r WebDAVRoot) EnsureFolder(rel string) (Folder, error)
```

EnsureFolder creates the folder and missing parents with MKCOL, then opens it. It returns an error wrapping ErrForbidden on 401 or 403, or a plain error when rel is invalid or MKCOL fails for another status.

#### WebDAVRoot.OpenFolder

```go
func (r WebDAVRoot) OpenFolder(rel string) (Folder, error)
```

OpenFolder opens an existing folder via WebDAV PROPFIND. It does not create the folder. It returns an error wrapping ErrNotExist when the server responds 404, ErrForbidden on 401 or 403, and ErrNotDir when the resource is not a collection. An invalid rel returns a plain error and does not call the server.