@revenexx/integrations-node-devkit 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +179 -0
- package/assets/schemas/README.md +22 -0
- package/dist/chunk-WPZPKJAS.js +1209 -0
- package/dist/chunk-WPZPKJAS.js.map +1 -0
- package/dist/cli.cjs +1967 -0
- package/dist/cli.cjs.map +1 -0
- package/dist/cli.js +779 -0
- package/dist/cli.js.map +1 -0
- package/dist/index.cjs +1269 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +308 -0
- package/dist/index.d.ts +308 -0
- package/dist/index.js +59 -0
- package/dist/index.js.map +1 -0
- package/dist/testing/index.cjs +215 -0
- package/dist/testing/index.cjs.map +1 -0
- package/dist/testing/index.d.cts +194 -0
- package/dist/testing/index.d.ts +194 -0
- package/dist/testing/index.js +179 -0
- package/dist/testing/index.js.map +1 -0
- package/package.json +86 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 revenexx GmbH
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
# @revenexx/integrations-node-devkit
|
|
2
|
+
|
|
3
|
+
Local development kit for Revenexx integration node packages. It gives node
|
|
4
|
+
developers two things without the full Docker stack:
|
|
5
|
+
|
|
6
|
+
1. **A mock Integrations API** the (WIP) Cockpit preview UI runs against, so you
|
|
7
|
+
can see the credentials / nodes / templates you're building rendered by the
|
|
8
|
+
real production UI components — including live **config-field resolving**.
|
|
9
|
+
2. **A unit-testing harness** for node `execute`, author-time resolvers, and
|
|
10
|
+
credential `test` / `resolve` / OAuth.
|
|
11
|
+
|
|
12
|
+
It is a **dev/CI-only** dependency and is **never** part of a built node bundle.
|
|
13
|
+
|
|
14
|
+
The mock invokes your package's real `loadOptions` / `resolveConfigSchema` /
|
|
15
|
+
`resolveOutputs` / `test` / `resolve` **in-process** — no bundle, no sandbox, no
|
|
16
|
+
PO-145 grant model (all intentionally omitted; this is dev-only). What you see
|
|
17
|
+
is your actual source, reloaded on save.
|
|
18
|
+
|
|
19
|
+
## Install
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install -D @revenexx/integrations-node-devkit
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Add a script to your node package:
|
|
26
|
+
|
|
27
|
+
```jsonc
|
|
28
|
+
// package.json
|
|
29
|
+
{
|
|
30
|
+
"scripts": {
|
|
31
|
+
"dev": "integrations-devkit"
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Preview
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
npm run dev
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Starts the mock API (default `http://localhost:3555/api/v1`) loaded from your
|
|
43
|
+
`src/index.ts`. Edit your nodes/credentials and the package hot-reloads.
|
|
44
|
+
|
|
45
|
+
### Preview with the Cockpit UI
|
|
46
|
+
|
|
47
|
+
The Cockpit UI ships as the **Nuxt module** `@revenexx/studio-integrations`
|
|
48
|
+
(Vue components + composables), *not* a static bundle — so it runs inside a Nuxt
|
|
49
|
+
host app. The devkit scaffolds and runs that host for you:
|
|
50
|
+
|
|
51
|
+
```jsonc
|
|
52
|
+
// package.json — `dev` (tsup --watch) is left untouched
|
|
53
|
+
{ "scripts": { "preview": "integrations-devkit preview" } }
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
npm run preview
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
This (1) scaffolds a minimal Nuxt host into `.revenexx-dev/preview/` (gitignored)
|
|
61
|
+
on first run, (2) `npm install`s it (heavy first time — pulls Nuxt + the studio
|
|
62
|
+
packages), (3) starts the mock API, and (4) runs `nuxt dev` wired to the mock.
|
|
63
|
+
Open **http://localhost:3000/integrations**.
|
|
64
|
+
|
|
65
|
+
No auth shim is needed: `@revenexx/studio-shared`'s standalone
|
|
66
|
+
`usePlatformAuth`/`usePlatformTenant` read a dev token/tenant from
|
|
67
|
+
`NUXT_PUBLIC_DEV_TOKEN` / `NUXT_PUBLIC_DEV_TENANT` (the devkit sets them; the
|
|
68
|
+
mock ignores the values). `runtimeConfig.public.integrationsApi` is pointed at
|
|
69
|
+
the mock automatically.
|
|
70
|
+
|
|
71
|
+
- `integrations-devkit init-preview` — only scaffold the host (then edit it; it's yours).
|
|
72
|
+
- `integrations-devkit preview --dir <path> --force` — custom dir / re-scaffold.
|
|
73
|
+
|
|
74
|
+
> **Scope:** the preview targets the **slimmed** studio build — node listing +
|
|
75
|
+
> credential/template management + **config-field resolving**. `studio-integrations`
|
|
76
|
+
> 0.1.4 still ships the workflow editor and renders `field.options` statically;
|
|
77
|
+
> config-field resolving needs the UI to `POST /nodes/{slug}/{version}/config:resolve`
|
|
78
|
+
> (the mock already serves it). The Temporal parts (run history, `…/runs/*`) are
|
|
79
|
+
> intentionally not mocked.
|
|
80
|
+
|
|
81
|
+
Pass `--ui <dir>` to `integrations-devkit` if you instead have a prebuilt static SPA.
|
|
82
|
+
|
|
83
|
+
### CLI options
|
|
84
|
+
|
|
85
|
+
| Flag | Default | Meaning |
|
|
86
|
+
| --- | --- | --- |
|
|
87
|
+
| `--entry <path>` | `src/index.ts` (else `dist/index.js`) | Package entry to load |
|
|
88
|
+
| `--seed <dir>` | `dev/seeds` | Committed seed directory |
|
|
89
|
+
| `--state <file>` | `.revenexx-dev/state.json` | Session overlay file |
|
|
90
|
+
| `--no-persist` | off | In-memory only; don't write the overlay |
|
|
91
|
+
| `--port <n>` | `$PORT` or `3555` | Listen port |
|
|
92
|
+
| `--ui <dir>` | resolve UI package | Static UI build to serve |
|
|
93
|
+
| `--no-ui` | off | Run API-only |
|
|
94
|
+
| `--open` | off | Open the preview in a browser |
|
|
95
|
+
| `reset` (subcommand) | | Delete the session overlay |
|
|
96
|
+
|
|
97
|
+
## Seeds + persistence (layered)
|
|
98
|
+
|
|
99
|
+
Three layers, base to top:
|
|
100
|
+
|
|
101
|
+
1. **Committed seeds** in `dev/seeds/` — stable instances checked into the repo.
|
|
102
|
+
Reference sensitive values via `${ENV_VAR}` (resolved from `.env`; only the
|
|
103
|
+
reference is committed, never the value):
|
|
104
|
+
|
|
105
|
+
```ts
|
|
106
|
+
// dev/seeds/index.ts
|
|
107
|
+
import type { DevSeeds } from '@revenexx/integrations-node-devkit';
|
|
108
|
+
|
|
109
|
+
const seeds: DevSeeds = {
|
|
110
|
+
secrets: [{ key: 'api-key', value: '${MY_API_KEY}' }],
|
|
111
|
+
credentials: [
|
|
112
|
+
{
|
|
113
|
+
id: 'smtp-dev', // stable id so workflows can reference it
|
|
114
|
+
credentialTypeSlug: 'revenexx:smtp',
|
|
115
|
+
name: 'Local SMTP',
|
|
116
|
+
config: { host: 'localhost', port: 1025, password: '${SMTP_PW}' },
|
|
117
|
+
},
|
|
118
|
+
],
|
|
119
|
+
};
|
|
120
|
+
export default seeds;
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
2. **`.revenexx-dev/state.json`** — interactive session state (what you create
|
|
124
|
+
in the preview UI). Gitignored, versioned, and disposable: on a schema-
|
|
125
|
+
version mismatch it is discarded rather than migrated, because the seeds are
|
|
126
|
+
the source of truth. `integrations-devkit reset` clears it.
|
|
127
|
+
|
|
128
|
+
3. **In-memory** (`--no-persist`) — nothing is written; reset on restart.
|
|
129
|
+
|
|
130
|
+
Add to your `.gitignore`:
|
|
131
|
+
|
|
132
|
+
```
|
|
133
|
+
.revenexx-dev/
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## Testing harness
|
|
137
|
+
|
|
138
|
+
```ts
|
|
139
|
+
import { describe, it, expect } from 'vitest';
|
|
140
|
+
import {
|
|
141
|
+
createMockContext,
|
|
142
|
+
createAuthorContext,
|
|
143
|
+
runCredentialResolve,
|
|
144
|
+
stubFetch,
|
|
145
|
+
fakeTokenEndpoint,
|
|
146
|
+
} from '@revenexx/integrations-node-devkit/testing';
|
|
147
|
+
|
|
148
|
+
// execute
|
|
149
|
+
const ctx = createMockContext({ credentials: { 'smtp-1': { host: 'mail' } } });
|
|
150
|
+
const res = await node.execute(ctx, { credentials: 'smtp-1' });
|
|
151
|
+
|
|
152
|
+
// author-time resolver
|
|
153
|
+
const authorCtx = createAuthorContext({ category: 'fruits' });
|
|
154
|
+
const options = await node.loadOptions(authorCtx, 'item');
|
|
155
|
+
|
|
156
|
+
// credential resolve + OAuth rotation, no network / broker
|
|
157
|
+
const stub = stubFetch(fakeTokenEndpoint({ accessToken: 'AT', refreshToken: 'RT' }));
|
|
158
|
+
const { result, persistDurableCreds } = await runCredentialResolve(cred, {
|
|
159
|
+
config: { clientId: 'x' },
|
|
160
|
+
durableCreds: { refreshToken: 'old' },
|
|
161
|
+
});
|
|
162
|
+
expect(persistDurableCreds).toHaveBeenCalledWith({ refreshToken: 'RT' });
|
|
163
|
+
stub.restore();
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
`vitest` is an optional peer dependency (the harness uses `vi` spies).
|
|
167
|
+
|
|
168
|
+
## Fidelity caveats
|
|
169
|
+
|
|
170
|
+
This is a faithful **dev** stand-in, not the production service:
|
|
171
|
+
|
|
172
|
+
- No auth / Zitadel / `X-Tenant-Id`; a single fixed dev tenant + principal.
|
|
173
|
+
- Author-time resolvers run in-process (not the forked sandbox), so bundle-build
|
|
174
|
+
states (`409 not built yet`) and the PO-145 grant/egress model are not
|
|
175
|
+
reproduced.
|
|
176
|
+
- Workflow-blob validation is light and schema-based; the production service
|
|
177
|
+
does deeper cross-validation on save.
|
|
178
|
+
- Workflow **run execution** is not included (v1).
|
|
179
|
+
# devkit
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Vendored JSON schemas
|
|
2
|
+
|
|
3
|
+
The mock API serves these at `GET /api/v1/schemas/{domain}[/{version}]` so the
|
|
4
|
+
Cockpit UI can run its client-side validation / form generation offline.
|
|
5
|
+
|
|
6
|
+
Naming: `<domain>-<version>.json` (split on the first dash). For example
|
|
7
|
+
`node-v0-draft.json` is served at both `/schemas/node/v0-draft` and
|
|
8
|
+
`/schemas/node` (latest).
|
|
9
|
+
|
|
10
|
+
These are snapshots of the integrations service output. To refresh, with the
|
|
11
|
+
Laravel service running:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
curl -s https://integrations.rvnxx.test/api/v1/schemas/node/v0-draft \
|
|
15
|
+
> node-v0-draft.json
|
|
16
|
+
curl -s https://integrations.rvnxx.test/api/v1/schemas/workflow/v0-draft \
|
|
17
|
+
> workflow-v0-draft.json
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
If a schema file is absent the corresponding endpoint returns 404 with a hint;
|
|
21
|
+
the preview still works for everything that doesn't need client-side schema
|
|
22
|
+
validation.
|