# MMM-NextcloudCookbook

A MagicMirror module that displays recipes from a read-only Nextcloud public
share. It includes a phone-friendly control page for choosing a recipe,
adjusting its number of portions, and entering or leaving recipe mode.

Create a public share for the folder configured as your Nextcloud Cookbook
recipe directory. Read-only permission is sufficient. Copy the public share
link; it should look like `https://cloud.example.test/s/SHARE_TOKEN`.

## MagicMirror configuration

```js
{
  module: "MMM-NextcloudCookbook",
  position: "fullscreen_above",
  config: {
    shareUrl: "https://cloud.example.test/s/SHARE_TOKEN",
    controlPath: "/MMM-NextcloudCookbook/control"
  }
}
```

For a password-protected public share, add `sharePassword`:

```js
config: {
  shareUrl: "https://cloud.example.test/s/SHARE_TOKEN",
  sharePassword: "PUBLIC_SHARE_PASSWORD"
}
```

MagicMirror sends module configuration to its browser clients. A public-share
URL is normally appropriate there because the token is already a scoped share
credential, but do not put a Nextcloud account password or app password in this
configuration.

For deployments that keep even the share token out of browser-visible
configuration, set `SECRET_NEXTCLOUD_COOKBOOK_SHARE_URL` and, if needed,
`SECRET_NEXTCLOUD_COOKBOOK_SHARE_PASSWORD` in the MagicMirror process
environment and omit the corresponding config values. Environment values take
precedence over module configuration and are read only by `node_helper.js`.

Open the controller at:

```text
http://mirror.example.test:8080/MMM-NextcloudCookbook/control
```

The share must contain Nextcloud Cookbook recipe folders with a `recipe.json`
file in each folder. The module uses Nextcloud's token-scoped public DAV API;
protected shares authenticate as Nextcloud's `anonymous` public-share user.

## Data-source decision: public WebDAV instead of the Cookbook API

Nextcloud Cookbook provides a REST API, but its external API requires
Nextcloud user credentials on every request. A read-only public-share token
cannot authenticate to that API.

This module intentionally reads the recipe files through Nextcloud's public
WebDAV interface because its job is limited to listing and displaying recipes.
That gives the mirror a narrower security boundary:

- access is scoped to the shared recipe folder;
- the share can be read-only;
- the mirror receives no general Nextcloud account credential; and
- the module cannot create, update, or delete recipes.

Cookbook stores recipes as ordinary `recipe.json` files, so WebDAV provides the
data required by this read-only display without relying on Cookbook's database
index. Index synchronization and reindexing matter when an external tool writes
recipe files; this module does not write them.

The Cookbook API would become preferable if the module later needs
Cookbook-native search, categories, keywords, imports, or recipe editing. In
that case, use a dedicated Nextcloud service user with read-only access to the
recipe folder and a dedicated app password rather than credentials for a
person's normal account.

References:

- [Cookbook API documentation](https://nextcloud.github.io/cookbook/dev/api/0.1.0/index.html)
- [Cookbook user documentation](https://nextcloud.github.io/cookbook/user/)

## Development

```bash
npm install
npm test
```