@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 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.