Mirror of https://github.com/roostorg/coop
github.com/roostorg/coop
Integration plugin: documentation file and info (#93)
+32
+31
docs/INTEGRATIONS_PLUGIN.md
+31
docs/INTEGRATIONS_PLUGIN.md
···
1
+
# Integrations plugin system
2
+
3
+
COOP supports **plugin-style integrations**: authors can ship integrations as separate packages (e.g. npm), and adopters can enable them via a **config file** without changing COOP source code. At startup the platform loads each enabled plugin and uses its manifest for metadata (title, docs, logos, model card, config fields). Adopters do not edit enums, server registries, or client logo maps. You just install the package and edit integrations config file.
4
+
5
+
## For integration authors
6
+
7
+
You build a package that exports a **plugin** (manifest + optional signals). The manifest describes the integration: id, name, version, docs link, logos, config fields, and any signals it provides. Logos can be files in the package (served by the platform) or URLs. If the integration needs per-org config (e.g. API keys), you define the fields in the manifest and the platform renders the config form and stores values.
8
+
9
+
**See the example package for a full reference implementation:** [**`coop-integration-example`**](https://github.com/roostorg/coop-integration-example). It includes a manifest, config field, model card, logos, and a sample signal. Use it as the template for building your own integration; the contract and types live in `@roostorg/types`.
10
+
11
+
## For adopters
12
+
13
+
1. **Install** the integration package (e.g. `npm install @roostorg/coop-integration-example` in the server app).
14
+
2. **Enable it** in the integrations config file. The server reads `server/integrations.config.json` by default, or the path in `INTEGRATIONS_CONFIG_PATH`. Example shape:
15
+
16
+
```json
17
+
{
18
+
"integrations": [
19
+
{ "package": "@roostorg/coop-integration-example", "enabled": true }
20
+
]
21
+
}
22
+
```
23
+
24
+
For local development like a local package, use `"package": "../coop-integration-example"` (path relative to the config file's directory). Do not put secrets in the config file; use the in-app integration config flow for API keys and similar.
25
+
26
+
3. **Use it** in the UI: the integration appears on the integrations page, orgs can set config, and if the plugin provides signals, they appear in the rule builder like built-in signals.
27
+
28
+
## Summary
29
+
30
+
- **Authors:** Implement the plugin contract (see `coop-integration-example` and `@roostorg/types`).
31
+
- **Adopters:** Add the package, add one entry to the integrations config, and the rest is driven by the plugin.
+1
docs/SUMMARY.md
+1
docs/SUMMARY.md
···
5
5
- [Development](DEVELOPMENT.md)
6
6
- [Architecture](ARCHITECTURE.md)
7
7
- [Integrating Signals](SIGNALS.md)
8
+
- [Integrations plugin](INTEGRATIONS_PLUGIN.md)
8
9
- [Data Warehouse Abstraction](DATA_WAREHOUSE_ABSTRACTION.md)
9
10
- [User Guide](USER_GUIDE.md)
10
11
- [API Keys and Authentication](API_AUTHENTICATION.md)