# Addon guide example

addons.desc.integration.guide

| Field | Value |
|---|---|
| Addon id | `integration-guide` |
| Kind | `integration` |
| Provides | `guide` |
| Engine | `wasm` |
| ABI | `0.3.0` |
| Version | 0.1.0 |
| Author | MythicalSystems |
| Source | `extensions/examples/addon-guide` |
| Permissions (shown at install) | none |

## Capabilities

| Capability | Value |
|---|---|
| [`emits`](capabilities.md) | `integration-guide:greeted` |
| [`events`](capabilities.md) | `invoice.paid`, `user.registered` |
| [`hooks`](capabilities.md) | `[{"event":"client.before_register","priority":"normal"},{"event":"login.before","fail_open":true,"priority":"high","timeout_ms":500},{"event":"before:integration-guide:greeted"},{"event":"order.before_place","ignore_cancelled":true,"priority":"highest"},{"event":"after:PUT /api/v1/client/profile","priority":"monitor"}]` |
| [`http`](capabilities.md) | `example.com` |
| [`jobs`](capabilities.md) | `[{"every_secs":3600,"op":"cleanup"}]` |
| [`kv`](capabilities.md) | true |
| [`mixins`](capabilities.md) | `[{"at":"after","target":"GET /api/v1/client/profile"}]` |
| [`routes`](capabilities.md) | `[{"access":"public","method":"GET","path":"/hello"},{"access":"client","method":"POST","path":"/greet"},{"access":"admin","method":"GET","path":"/stats","permission":"reports.read"}]` |
| [`secrets`](capabilities.md) | `api_token` |
| [`ui`](capabilities.md) | `iframe` |

## Events and hooks

| What | Value |
|---|---|
| Listens to (`events`) | `invoice.paid`, `user.registered` |
| Hooks | `client.before_register`, `login.before`, `before:integration-guide:greeted`, `order.before_place`, `after:PUT /api/v1/client/profile` |
| Emits | `integration-guide:greeted` |
| Mixins | `GET /api/v1/client/profile` (after) |
| Scheduled jobs | `cleanup` every 3600 s |

## Settings and secrets

| Setting | Type | Required |
|---|---|---|
| `greeting` | `text` | no |
| `api_token` | `secret` | no |

Secrets (stored encrypted, never returned by the API): `api_token`.

Outbound HTTP allowed to: `example.com`. `$server` is the hostname of the server configured for the product, `$setting:<key>` the host of that setting.

## HTTP routes

Mounted under `/api/v1/addons/integration-guide/`.

| Method | Path | Access | Permission |
|---|---|---|---|
| GET | `/hello` | public | - |
| POST | `/greet` | client | - |
| GET | `/stats` | admin | `reports.read` |

## UI

Pages: `stats` (admin), `frame` (client). Slots: `client.dashboard`, `admin.invoices.toolbar`. See [Widgets and slots](widgets.md).

## addon.json

_extensions/examples/addon-guide/addon.json_

```json
{
  "abi": "0.3.0",
  "author": "MythicalSystems",
  "capabilities": {
    "emits": [
      "integration-guide:greeted"
    ],
    "events": [
      "invoice.paid",
      "user.registered"
    ],
    "hooks": [
      {
        "event": "client.before_register",
        "priority": "normal"
      },
      {
        "event": "login.before",
        "fail_open": true,
        "priority": "high",
        "timeout_ms": 500
      },
      {
        "event": "before:integration-guide:greeted"
      },
      {
        "event": "order.before_place",
        "ignore_cancelled": true,
        "priority": "highest"
      },
      {
        "event": "after:PUT /api/v1/client/profile",
        "priority": "monitor"
      }
    ],
    "http": [
      "example.com"
    ],
    "jobs": [
      {
        "every_secs": 3600,
        "op": "cleanup"
      }
    ],
    "kv": true,
    "mixins": [
      {
        "at": "after",
        "target": "GET /api/v1/client/profile"
      }
    ],
    "routes": [
      {
        "access": "public",
        "method": "GET",
        "path": "/hello"
      },
      {
        "access": "client",
        "method": "POST",
        "path": "/greet"
      },
      {
        "access": "admin",
        "method": "GET",
        "path": "/stats",
        "permission": "reports.read"
      }
    ],
    "secrets": [
      "api_token"
    ],
    "ui": [
      "iframe"
    ]
  },
  "description": "addons.desc.integration.guide",
  "engine": "wasm",
  "i18n": {
    "en": {
      "badge": "Guide",
      "frame_title": "Guide frame",
      "hello": "Hello from the guide addon.",
      "key": "Counter",
      "stats_hint": "Counters kept by the guide addon.",
      "stats_title": "Guide stats",
      "value": "Value"
    },
    "ro": {
      "badge": "Ghid",
      "frame_title": "Cadru ghid",
      "hello": "Salut de la addon-ul ghid.",
      "key": "Contor",
      "stats_hint": "Contoare ținute de addon-ul ghid.",
      "stats_title": "Statistici ghid",
      "value": "Valoare"
    }
  },
  "id": "integration-guide",
  "kind": "integration",
  "name": "Addon guide example",
  "permissions": [],
  "provides": "guide",
  "settings": [
    {
      "key": "greeting",
      "kind": "text",
      "label": "Greeting text",
      "required": false
    },
    {
      "key": "api_token",
      "kind": "secret",
      "label": "API token",
      "required": false
    }
  ],
  "ui": {
    "pages": [
      {
        "area": "admin",
        "body": {
          "children": [
            {
              "text": "{{t:plugin.integration-guide.stats_hint}}",
              "type": "text"
            },
            {
              "columns": [
                {
                  "header": "plugin.integration-guide.key",
                  "value": "{{row.key}}"
                },
                {
                  "header": "plugin.integration-guide.value",
                  "value": "{{row.value}}"
                }
              ],
              "rows": "{{data.stats.rows}}",
              "type": "table"
            }
          ],
          "type": "stack"
        },
        "data": {
          "stats": {
            "get": "/api/v1/addons/integration-guide/stats"
          }
        },
        "icon": "ChartBar",
        "id": "stats",
        "nav": true,
        "title": "plugin.integration-guide.stats_title"
      },
      {
        "area": "client",
        "frame": {
          "height": 200,
          "src": "assets/ui.html"
        },
        "icon": "AppWindow",
        "id": "frame",
        "nav": true,
        "title": "plugin.integration-guide.frame_title"
      }
    ],
    "slots": [
      {
        "body": {
          "text": "{{t:plugin.integration-guide.hello}}",
          "type": "alert"
        },
        "slot": "client.dashboard"
      },
      {
        "body": {
          "text": "{{t:plugin.integration-guide.badge}}",
          "type": "badge"
        },
        "order": 5,
        "slot": "admin.invoices.toolbar"
      }
    ]
  },
  "version": "0.1.0",
  "wasm": "addon.wasm"
}
```