DriverVault/API Server/internal/plugins/README.md

# Building DriverVault Plugins

A **plugin** integrates an external third-party service (vehicle data, parts
catalogs, notifications, file storage, …) behind one uniform contract. There are
two kinds:

| Kind | Written as | Added by | Rebuild? | Use when |
|---|---|---|---|---|
| **built-in** | Go code in this repo | a rebuild | yes | first-party, high-trust, type-safe connectors |
| **external** | any HTTP service | registering a URL at runtime | **no** | third-party / less-trusted / independently deployed |

Both implement the same behaviour; the server treats them identically. Enable
state and per-plugin config persist to PocketBase and load on boot. Every plugin
is managed by a **superadmin** from the panel (`/`) or the `/api/admin/plugins*`
API.

---

## The contract

All plugins satisfy the Go interface in [`plugin.go`](plugin.go):

```go
type Plugin interface {
    Descriptor() Descriptor
    Init(ctx context.Context, config map[string]string) error
    HealthCheck(ctx context.Context) Health
    Invoke(ctx context.Context, action string, params json.RawMessage) (json.RawMessage, error)
    Shutdown(ctx context.Context) error
}
```

- **`Descriptor`** — static metadata (name, provider, version, capabilities,
  auth type, config fields). Drives the panel UI.
- **`Init`** — called with the resolved config (secrets included) whenever the
  plugin is enabled or its config changes. Prepare clients/tokens here.
- **`HealthCheck`** — probe the upstream and classify: `Health{Status, LatencyMs, Detail}`
  where `Status` is `StatusOK` / `StatusDegraded` / `StatusDown`.
- **`Invoke`** — run a named capability. There is no *generic* invoke endpoint yet,
  but this is live: the integration routes and the vehicle-provider layer call it
  through `Manager.InvokeWith` / `InvokeBatchWith`, so implement it properly. It
  must be safe for concurrent use — the live instance is shared across requests,
  and `InvokeBatchWith` runs a batch of actions in parallel on one instance.
- **`Shutdown`** — release resources.

### Descriptor & config fields

```go
Descriptor{
    Name:         "acme",              // unique id, [a-z0-9-]
    Provider:     "ACME Corp",         // human label
    Version:      "1.0.0",
    Kind:         plugins.KindBuiltin, // or KindExternal
    Capabilities: []plugins.Capability{
        {ID: "widgets.list", Method: "GET", Endpoint: "/widgets", Description: "List widgets."},
    },
    AuthType:     plugins.AuthAPIKey,  // None | APIKey | Basic | OAuth2 | Webhook (metadata only)
    ConfigFields: []plugins.ConfigField{
        {Key: "apiKey", Label: "API key", Type: "password", Required: true, Secret: true,
         Help: "Found under ACME → Settings → API."},
        {Key: "region", Label: "Region", Type: "text", Help: "e.g. eu-west-1"},
    },
}
```

`ConfigField.Type` is `"text"`, `"password"`, or `"number"` (form input hint).
Set **`Secret: true`** for credentials — the server never echoes them back in
clear; the panel shows a mask (`••••••••`), and on save a field left at the mask
keeps its stored value (so operators don't retype secrets). **`Required: true`**
fields must be non-empty before the plugin can be enabled.

---

## Building a built-in plugin

1. **Create a package** under `internal/plugins/builtin/<name>/`.
2. **Implement `Plugin`** and **register it in `init()`**.
3. **Blank-import** your package from [`builtin/builtin.go`](builtin/builtin.go).
4. **Rebuild** the server.

### Minimal example — `internal/plugins/builtin/acme/acme.go`

```go
package acme

import (
    "context"
    "encoding/json"
    "net/http"
    "strings"
    "time"

    "drivervault/apiserver/internal/plugins"
)

func init() {
    plugins.Register("acme", func() plugins.Plugin { return &Plugin{} })
}

type Plugin struct {
    apiKey string
    region string
    client *http.Client
}

func (p *Plugin) Descriptor() plugins.Descriptor {
    return plugins.Descriptor{
        Name: "acme", Provider: "ACME Corp", Version: "1.0.0",
        Kind: plugins.KindBuiltin, AuthType: plugins.AuthAPIKey,
        Capabilities: []plugins.Capability{
        {ID: "widgets.list", Method: "GET", Endpoint: "/widgets", Description: "List widgets."},
    },
        ConfigFields: []plugins.ConfigField{
            {Key: "apiKey", Label: "API key", Type: "password", Required: true, Secret: true},
            {Key: "region", Label: "Region", Type: "text"},
        },
    }
}

func (p *Plugin) Init(_ context.Context, config map[string]string) error {
    p.apiKey = strings.TrimSpace(config["apiKey"])
    p.region = strings.TrimSpace(config["region"])
    p.client = &http.Client{Timeout: 10 * time.Second}
    return nil
}

func (p *Plugin) HealthCheck(ctx context.Context) plugins.Health {
    start := time.Now()
    req, _ := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.acme.example/ping", nil)
    req.Header.Set("Authorization", "Bearer "+p.apiKey)
    resp, err := p.client.Do(req)
    lat := time.Since(start).Milliseconds()
    if err != nil {
        return plugins.Health{Status: plugins.StatusDown, LatencyMs: lat, Detail: err.Error()}
    }
    defer resp.Body.Close()
    if resp.StatusCode >= 200 && resp.StatusCode < 300 {
        return plugins.Health{Status: plugins.StatusOK, LatencyMs: lat, Detail: "reachable"}
    }
    return plugins.Health{Status: plugins.StatusDown, LatencyMs: lat, Detail: "HTTP " + resp.Status}
}

func (p *Plugin) Invoke(ctx context.Context, action string, params json.RawMessage) (json.RawMessage, error) {
    // Implement your capabilities; return normalized JSON. Must be safe for
    // concurrent use — one instance serves many requests.
    return json.RawMessage(`{"ok":true}`), nil
}

func (p *Plugin) Shutdown(context.Context) error { return nil }
```

### Register it for compilation — `internal/plugins/builtin/builtin.go`

```go
import (
    _ "drivervault/apiserver/internal/plugins/builtin/acme"
)
```

### Rebuild

```powershell
cd "API Server"
go build -o bin/api-server.exe ./cmd/server
```

Restart the server. The plugin appears in the panel's **Plugins** card,
**disabled** by default.

> DriverVault ships two built-in connectors today — `toyota` (Toyota Connected /
> MyToyota, read-only vehicle data) and `anker-solix` (Anker Solix V1 EV charger)
> — both blank-imported from `builtin/builtin.go`. The **external** kind below
> needs no rebuild and is the easier place to start a new one.

---

## Building an external plugin (no rebuild)

An external plugin is **any HTTP service** you host (Go recommended, but any
language works). You register its base URL at runtime; the server drives it over
a tiny JSON contract.

### The HTTP contract

| Method & path | Purpose | Response |
|---|---|---|
| `GET {base}/manifest` | describe the plugin (optional) | `{provider, version, capabilities, authType, configFields}` |
| `GET {base}/health` | health probe (required) | `2xx` = healthy; optional body `{status, detail}` |
| `POST {base}/invoke` | run a capability (optional; unused in v1) | `{action, params}` in → arbitrary JSON out |

Health rules the server applies: transport error or `5xx` → `down`; `2xx` → `ok`;
anything else → `degraded`. An explicit `{"status":"ok|degraded|down","detail":"…"}`
body overrides the status-code heuristic. Bodies are size-limited (health 64 KiB,
manifest 1 MiB).

### Minimal example — a Go plugin service

```go
package main

import (
    "encoding/json"
    "net/http"
)

func main() {
    http.HandleFunc("/manifest", func(w http.ResponseWriter, r *http.Request) {
        json.NewEncoder(w).Encode(map[string]any{
            "provider":     "ACME Cloud",
            "version":      "2.1.0",
            "authType":     "apikey",
            "capabilities": []map[string]any{
                {"id": "widgets.list", "method": "GET", "endpoint": "/widgets", "description": "List widgets."},
            }, // a plain []string{"widgets.list"} is also accepted
            "configFields": []map[string]any{
                {"key": "apiKey", "label": "API key", "type": "password", "required": true, "secret": true},
            },
        })
    })
    http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
        json.NewEncoder(w).Encode(map[string]any{"status": "ok", "detail": "acme cloud reachable"})
    })
    http.HandleFunc("/invoke", func(w http.ResponseWriter, r *http.Request) {
        var in struct {
            Action string          `json:"action"`
            Params json.RawMessage `json:"params"`
        }
        json.NewDecoder(r.Body).Decode(&in)
        json.NewEncoder(w).Encode(map[string]any{"ok": true, "action": in.Action})
    })
    http.ListenAndServe(":9100", nil)
}
```

### Register it

From the panel's **Plugins** card → *Register external plugin* (name + base URL),
or via the API:

```bash
curl -X POST http://localhost:8080/api/admin/plugins \
  -H "Authorization: $SUPERADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"acme-cloud","baseURL":"http://127.0.0.1:9100","provider":"ACME Cloud"}'
```

It starts **disabled**; enable it and run a health check from the panel. Because
it runs as its own process/container, an external plugin is also the
**sandboxing** path for less-trusted integrations.

---

## Lifecycle, config & secrets

- **Enable/disable** and **config** persist to PocketBase: the `app_settings`
  record keyed `global`, in its `pluginSettings` field. That is the top (L1)
  layer of the integration cascade, stored the same way the org (L2) and user
  (L3) layers are. Enabling calls `Init`; disabling calls `Shutdown`.
- **Before the settings have been read** — a cold database, or a service account
  still to be configured — every `/api/admin/plugins*` endpoint answers **503**
  and no write is accepted. The server never treats an unreachable database as
  "no plugins configured", so an outage cannot quietly erase the settings; it
  retries in the background until the read succeeds.
- **If the `app_settings` collection is missing** — an upgrade on a stack that
  runs with `PB_BOOTSTRAP=false`, so the on-boot schema pass never created it —
  the server creates that one collection itself and reads again. A missing
  collection is told apart from a database that is merely unreachable, because
  the remedy differs: creating collections is the wrong reflex during an outage.
- **Secrets** (`Secret: true` fields) are returned masked. On save, a field still
  equal to the mask keeps its stored value; send a new value to change it, or an
  empty string to clear it.
- **Required** fields are validated when enabling — enabling fails with a clear
  error if one is blank.
- If `Init` fails (e.g. bad credentials), the state is still saved and the API
  returns the plugin plus a `warning`; fix the config and re-save.

---

## Managing plugins (superadmin API)

All endpoints require a superadmin bearer token (`Authorization: <token>` from
`POST /api/auth/login`). See the panel's **Management API** reference too.

| Method | Path | Body | Purpose |
|---|---|---|---|
| `GET` | `/api/admin/plugins` | — | list all plugins + state + last health |
| `GET` | `/api/admin/plugins/{name}` | — | one plugin |
| `PUT` | `/api/admin/plugins/{name}` | `{enabled?, config?}` | enable/disable + configure |
| `POST` | `/api/admin/plugins` | `{name, baseURL, provider?}` | register an external plugin |
| `DELETE` | `/api/admin/plugins/{name}` | — | remove an external plugin (built-ins only disable) |
| `POST` | `/api/admin/plugins/{name}/health` | — | run a health check now |

---

## Testing your plugin

1. Build + restart (built-in) or start your service (external) and register it.
2. `GET /api/admin/plugins` → confirm your descriptor, config fields, capabilities.
3. `PUT /api/admin/plugins/{name} {"enabled":true, "config":{…}}` → enable with config.
4. `POST /api/admin/plugins/{name}/health` → confirm the live probe classifies correctly.
5. Restart the server → confirm state reloads from PocketBase.

A Go unit test can exercise a built-in directly:

```go
p := &acme.Plugin{}
_ = p.Init(context.Background(), map[string]string{"apiKey": "test"})
if h := p.HealthCheck(context.Background()); h.Status == "" {
    t.Fatal("expected a health status")
}
```

---

## Not yet implemented (roadmap)

The contract is shaped for these; see [`doc.go`](doc.go):

- **Generic invocation API** — an endpoint to call *any* plugin's `Invoke` from a
  client, with a normalized request/response envelope. The purpose-built callers
  exist (`Manager.InvokeWith` / `InvokeBatchWith`, driven by the integration routes
  and `internal/api/vehicleproviders.go`); what is missing is the generic route.
- **Resilience** — retry/backoff, circuit breaker, per-plugin latency/error metrics.
- **Per-tenant credentials _for arbitrary plugins_** — the two built-in connectors
  already have them, through the hand-written `/api/integrations/toyota` and
  `/api/integrations/anker-solix` routes and their **superadmin → org admin →
  user** config cascade. What is missing is the generic version: per-org/per-user
  config keyed off `ConfigFields`, so a newly registered plugin gets the same
  treatment without new endpoints.
- **Audit logging** of plugin access. (Charger *control* commands are already
  audited to the `control_audit` collection; this is the wider plugin case.)

Until the generic invocation API lands, `Invoke` is reachable only through the
purpose-built routes: the two integrations' own endpoints, and the vehicle-provider
layer that builds a car from a manufacturer account and feeds the car's provider
tab (see `internal/api/vehicleproviders.go`).