Mirror of https://github.com/roostorg/coop-integration-example
github.com/roostorg/coop-integration-example
1# @roostorg/coop-integration-example
2
3Example [Coop](https://github.com/roostorg/coop) integration plugin. Reference repository showing how to build a custom integration and signals for use in Coop.
4
5- **Integration config** – saving and loading per-org config (e.g. “True percentage”)
6- **Routing rules** – using the plugin signal in conditions
7- **Automated enforcement** – the same signal in enforcement rules
8
9## What it provides
10
11- **Integration:** `COOP_INTEGRATION_EXAMPLE`
12- **Signal 1 – Random Signal Selection** (`RANDOM_SIGNAL_SELECTION`): Returns `true` or `false` at random. The probability (0–100%) comes from the org’s integration config (“True percentage”). Set e.g. `70` in Org settings → Integrations; the signal returns `true` about 70% of the time. Use this to test config saving and boolean conditions.
13- **Signal 2 – Random Score** (`RANDOM_SCORE`): Returns a random number from **0 up to (but not including) 100**—the same 0–100 style as “True percentage,” so thresholds feel consistent. No integration config needed. In the rule builder set a **threshold** (e.g. `50`) and choose **above** or **below**. Use this to test numeric score conditions (e.g. “score ≥ 50” or “score < 30”).
14
15## Install
16
17**From this repo (development):**
18
19```bash
20git clone https://github.com/roostorg/coop-integration-example.git
21cd coop-integration-example
22npm install
23npm run build
24```
25
26**From npm:**
27
28```bash
29npm install @roostorg/coop-integration-example
30```
31
32## Configure in Coop
33
34In your Coop `integrations.config.json` (or `INTEGRATIONS_CONFIG_PATH`), add:
35
36**Local path (development):**
37If you cloned this repo next to your Coop server directory, use a path relative to the server (e.g. from `server/`):
38
39```json
40{
41 "integrations": [
42 { "package": "../coop-integration-example", "enabled": true }
43 ]
44}
45```
46
47**From npm:**
48
49```json
50{
51 "integrations": [
52 { "package": "@roostorg/coop-integration-example", "enabled": true }
53 ]
54}
55```
56
57Restart the Coop server so it loads the plugin.
58
59## Use in the app
60
611. **Org settings → Integrations** – you should see Coop Integration Example”. Open it and set **True percentage (0–100)** (e.g. `70`) for Random Signal Selection. Save.
622. **Rules (routing or enforcement)** – when adding a condition:
63 - **Random Signal Selection**: Pick that signal; the condition uses your configured percentage (true/false).
64 - **Random Score**: Pick “Random Score”, then set a **threshold** on the 0–100 scale (e.g. `50`) and choose **above** or **below**. The rule compares the random score to your threshold.
65
66## Contract
67
68This package implements the Coop plugin contract from `@roostorg/types`:
69
70- **Default export:** `CoopIntegrationPlugin` with `manifest` and `createSignals(context)`.
71- **Manifest:** `id`, `name`, `version`, `requiresConfig`, `configurationFields`, `signalTypeIds`, `modelCard` (must include every section id in `REQUIRED_MODEL_CARD_SECTION_IDS` from `@roostorg/types`; call `assertModelCardHasRequiredSections(modelCard)` when registering).
72- **createSignals:** Returns two descriptors:
73 - `RANDOM_SIGNAL_SELECTION`: `run(input)` uses `context.getCredential(orgId)` for true percentage; returns `{ outputType: { scalarType: 'BOOLEAN' }, score: boolean }`.
74 - `RANDOM_SCORE`: `run()` returns `{ outputType: { scalarType: 'NUMBER' }, score: number }` in **[0, 100)** (`Math.random() * 100`); no config. Threshold is set in the rule on the same scale (above/below).
75
76## Publishing
77
78CI runs on push/PR (build only). To publish to npm:
79
801. Create a [GitHub release](https://github.com/roostorg/coop-integration-example/releases) (tag e.g. `v1.0.1`). The **Publish to npm** workflow runs on release and runs `npm publish --access public`.
812. Add **NPM_TOKEN** in this repo’s secrets (Settings → Secrets and variables → Actions): an npm [automation token](https://docs.npmjs.com/creating-and-viewing-access-tokens) with publish permission for `@roostorg/coop-integration-example`.
82
83You can also trigger **Publish to npm** manually from the Actions tab (workflow_dispatch).