@revenexx/integrations-node-devkit 0.8.0 → 0.8.2
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/README.md +2 -1
- package/dist/cli-args.d.ts +33 -0
- package/dist/cli.cjs.map +1 -1
- package/dist/env.d.ts +70 -0
- package/dist/errors.d.ts +21 -0
- package/dist/http.d.ts +23 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +8 -474
- package/dist/loader.d.ts +57 -0
- package/dist/persistence.d.ts +60 -0
- package/dist/ports.d.ts +24 -0
- package/dist/preview/child-env.d.ts +32 -0
- package/dist/preview/host.d.ts +147 -0
- package/dist/preview/pid.d.ts +14 -0
- package/dist/preview/registry.d.ts +40 -0
- package/dist/projections.d.ts +29 -0
- package/dist/resolve.d.ts +125 -0
- package/dist/server.d.ts +13 -0
- package/dist/state-rules.d.ts +32 -0
- package/dist/store.d.ts +184 -0
- package/dist/testing/author.d.ts +33 -0
- package/dist/testing/context.d.ts +96 -0
- package/dist/testing/credentials.d.ts +66 -0
- package/dist/testing/fetch.d.ts +57 -0
- package/dist/testing/index.cjs.map +1 -1
- package/dist/testing/index.d.ts +5 -253
- package/dist/testing/index.js.map +1 -1
- package/dist/testing/mock.d.ts +12 -0
- package/package.json +7 -6
- package/preview-host/package.json +3 -3
- package/dist/index.d.cts +0 -482
- package/dist/testing/index.d.cts +0 -253
package/dist/index.d.ts
CHANGED
|
@@ -1,474 +1,3 @@
|
|
|
1
|
-
import { INode, ICredential, ITemplateDescription, NodeManifest, IConfigOption, IConfigField, IOutputPort, ICredentialDescription, INodeDescription, ICredentialResolveResult, ICredentialTestResult } from '@revenexx/integrations-node-sdk';
|
|
2
|
-
import http from 'node:http';
|
|
3
|
-
|
|
4
|
-
/**
|
|
5
|
-
* `.env` loading for the CLI.
|
|
6
|
-
*
|
|
7
|
-
* Seeds reference secrets as `${VAR}` and {@link interpolateEnv} resolves those
|
|
8
|
-
* from `process.env`, so without this the documented workflow — commit the
|
|
9
|
-
* reference, keep the value in `.env` — only worked if the developer exported
|
|
10
|
-
* the variables by hand.
|
|
11
|
-
*
|
|
12
|
-
* Loading happens before option parsing, because the CLI reads `PORT` for its
|
|
13
|
-
* default port; a `.env` that sets `PORT` would otherwise be read too late.
|
|
14
|
-
*
|
|
15
|
-
* Exactly one file is ever loaded: `.env` by default, or the one named by
|
|
16
|
-
* `--env`, which *replaces* the default rather than layering on top of it.
|
|
17
|
-
* "Use this env file" is what the flag reads like, so leaving `.env` in play
|
|
18
|
-
* would be the surprise. `--no-env` loads none.
|
|
19
|
-
*
|
|
20
|
-
* `process.loadEnvFile` deliberately does not overwrite variables that are
|
|
21
|
-
* already set, so a shell-provided value always beats the file:
|
|
22
|
-
*
|
|
23
|
-
* REVENEXX_DEV_API_KEY=… npm run preview
|
|
24
|
-
*
|
|
25
|
-
* The flag is `--env`, *not* `--env-file`: Node reserves `--env-file` and
|
|
26
|
-
* `--env-file-if-exists` and acts on them wherever they appear, including after
|
|
27
|
-
* the script path. `node cli.js --env-file missing` therefore dies inside Node
|
|
28
|
-
* with exit code 9 before this module is ever reached, so the devkit cannot own
|
|
29
|
-
* that name. {@link nodeOwnedEnvFlag} spots the mistake and explains it.
|
|
30
|
-
*
|
|
31
|
-
* `--env` takes a path rather than Laravel's bare environment name, because it
|
|
32
|
-
* mirrors Node's flag and because a path can point outside the package. A value
|
|
33
|
-
* that looks like it was meant as a name still gets a pointed error — see
|
|
34
|
-
* {@link missingFileMessage}.
|
|
35
|
-
*/
|
|
36
|
-
/** Minimum Node version shipping `process.loadEnvFile`. */
|
|
37
|
-
declare const ENV_FILE_MIN_NODE = "20.12";
|
|
38
|
-
interface EnvFileChoice {
|
|
39
|
-
/** Absolute path to load, or `null` when `--no-env` disabled loading. */
|
|
40
|
-
path: string | null;
|
|
41
|
-
/** True when the file was named with `--env` rather than defaulted to. */
|
|
42
|
-
explicit: boolean;
|
|
43
|
-
/** The `--env` value exactly as typed, kept for {@link missingFileMessage}. */
|
|
44
|
-
raw?: string;
|
|
45
|
-
}
|
|
46
|
-
/**
|
|
47
|
-
* Returns the Node-owned env flag present in `argv`, if any. Node has already
|
|
48
|
-
* acted on it by the time the CLI runs — this exists only so the CLI can say so
|
|
49
|
-
* instead of leaving the user wondering why `--env-file` behaved oddly.
|
|
50
|
-
*/
|
|
51
|
-
declare function nodeOwnedEnvFlag(argv: string[]): string | null;
|
|
52
|
-
/**
|
|
53
|
-
* Decides which env file to load. Pure — touches neither disk nor `process.env`.
|
|
54
|
-
*
|
|
55
|
-
* A repeated `--env` resolves to the last one, matching every other option in
|
|
56
|
-
* the CLI, whose parse loop simply overwrites. Every occurrence is still
|
|
57
|
-
* validated, so a malformed earlier one is reported rather than skipped.
|
|
58
|
-
*/
|
|
59
|
-
declare function resolveEnvFile(argv: string[], cwd?: string): EnvFileChoice;
|
|
60
|
-
interface LoadEnvFileOptions {
|
|
61
|
-
cwd?: string;
|
|
62
|
-
warn?: (message: string) => void;
|
|
63
|
-
}
|
|
64
|
-
/**
|
|
65
|
-
* Loads the env file chosen by {@link resolveEnvFile} into `process.env` and
|
|
66
|
-
* returns its path, or `null` when nothing was loaded.
|
|
67
|
-
*
|
|
68
|
-
* A missing *default* `.env` is fine — most packages do not have one. A file
|
|
69
|
-
* asked for by name and missing is an error: ignoring it would hide a typo and
|
|
70
|
-
* resurface much later as a puzzling `Seed references ${X}` failure. There is no
|
|
71
|
-
* fallback to `.env` in that case, since naming a file replaces the default.
|
|
72
|
-
*/
|
|
73
|
-
declare function loadEnvFile(argv: string[], options?: LoadEnvFileOptions): string | null;
|
|
74
|
-
|
|
75
|
-
/**
|
|
76
|
-
* An error that maps to an HTTP status + JSON body in the mock API, mirroring
|
|
77
|
-
* Laravel's `{message}` / `{message, errors}` envelopes.
|
|
78
|
-
*/
|
|
79
|
-
declare class DevApiError extends Error {
|
|
80
|
-
readonly status: number;
|
|
81
|
-
readonly errors?: Record<string, string[]> | undefined;
|
|
82
|
-
constructor(status: number, message: string, errors?: Record<string, string[]> | undefined);
|
|
83
|
-
}
|
|
84
|
-
|
|
85
|
-
/** Identity of the npm package the nodes came from, as `GET /nodes` reports it. */
|
|
86
|
-
interface PackageInfo {
|
|
87
|
-
name: string;
|
|
88
|
-
version: string;
|
|
89
|
-
label: string;
|
|
90
|
-
}
|
|
91
|
-
/**
|
|
92
|
-
* A node package loaded into the dev process: its live `NODES` / `CREDENTIALS`
|
|
93
|
-
* / `TEMPLATES` instances (so author-time resolvers, `test`, and `resolve` can
|
|
94
|
-
* be invoked in-process — no bundle, no sandbox) plus the derived manifest the
|
|
95
|
-
* mock API serves.
|
|
96
|
-
*/
|
|
97
|
-
interface LoadedPackage {
|
|
98
|
-
nodes: INode[];
|
|
99
|
-
credentials: ICredential[];
|
|
100
|
-
templates: ITemplateDescription[];
|
|
101
|
-
manifest: NodeManifest;
|
|
102
|
-
/** Reported as each node's `package`; the contract declares it non-null. */
|
|
103
|
-
packageInfo: PackageInfo;
|
|
104
|
-
/** Stands in for the service's per-node `created_at`/`updated_at`. */
|
|
105
|
-
loadedAt: string;
|
|
106
|
-
}
|
|
107
|
-
interface PackageExports {
|
|
108
|
-
NODES?: unknown;
|
|
109
|
-
CREDENTIALS?: unknown;
|
|
110
|
-
TEMPLATES?: unknown;
|
|
111
|
-
}
|
|
112
|
-
/**
|
|
113
|
-
* Validates a package's module exports and builds a {@link LoadedPackage}.
|
|
114
|
-
* Mirrors the checks in the SDK's `rvnxx-nodes manifest` CLI so the dev loop
|
|
115
|
-
* and the build produce identical manifests.
|
|
116
|
-
*/
|
|
117
|
-
declare function resolveExports(mod: PackageExports, packageInfo?: PackageInfo): LoadedPackage;
|
|
118
|
-
/**
|
|
119
|
-
* Registers the `tsx` ESM loader once per process so `import()` can load
|
|
120
|
-
* TypeScript sources directly. Idempotent.
|
|
121
|
-
*/
|
|
122
|
-
declare function ensureTsxRegistered(): Promise<void>;
|
|
123
|
-
/** Imports a module by path, registering tsx first for TypeScript sources. */
|
|
124
|
-
declare function importFresh<T = unknown>(entryPath: string): Promise<T>;
|
|
125
|
-
/**
|
|
126
|
-
* Imports a package entry and resolves its exports. Supports TypeScript
|
|
127
|
-
* sources directly (via `tsx`) so the preview runs against the developer's
|
|
128
|
-
* live `src/`, not a built artifact. A cache-busting query is appended so
|
|
129
|
-
* repeated calls (hot-reload) re-evaluate the module.
|
|
130
|
-
*/
|
|
131
|
-
declare function loadPackageFromEntry(entryPath: string): Promise<LoadedPackage>;
|
|
132
|
-
|
|
133
|
-
/**
|
|
134
|
-
* In-memory data store backing the mock Integrations API. Holds the tenant-
|
|
135
|
-
* scoped resources a developer creates in the preview (credentials, secrets,
|
|
136
|
-
* workflows, triggers). Serializable so a session can be persisted to and
|
|
137
|
-
* rehydrated from `.revenexx-dev/state.json`.
|
|
138
|
-
*/
|
|
139
|
-
declare const DEV_TENANT_ID = "dev-tenant";
|
|
140
|
-
interface CredentialRecord {
|
|
141
|
-
id: string;
|
|
142
|
-
tenantId: string;
|
|
143
|
-
credentialTypeSlug: string;
|
|
144
|
-
name: string;
|
|
145
|
-
status: string;
|
|
146
|
-
/** Full user-entered config, including secret fields (never sent to the UI verbatim). */
|
|
147
|
-
config: Record<string, unknown>;
|
|
148
|
-
/** System-managed long-lived secrets (e.g. an OAuth refresh token). */
|
|
149
|
-
durableCreds: Record<string, unknown> | null;
|
|
150
|
-
/** Outcome of the last `POST /credentials/{id}/test`, which the contract reports. */
|
|
151
|
-
lastTestAt: string | null;
|
|
152
|
-
lastTestOk: boolean | null;
|
|
153
|
-
lastTestMessage: string | null;
|
|
154
|
-
createdAt: string;
|
|
155
|
-
updatedAt: string;
|
|
156
|
-
}
|
|
157
|
-
interface SecretRecord {
|
|
158
|
-
key: string;
|
|
159
|
-
value: string;
|
|
160
|
-
createdAt: string;
|
|
161
|
-
updatedAt: string;
|
|
162
|
-
}
|
|
163
|
-
/**
|
|
164
|
-
* Field names follow the service's contract: the graph is `blob`, tagged with the
|
|
165
|
-
* `blob_definition_version` it was written against. The mock used to call it
|
|
166
|
-
* `definition`, which meant a workflow saved from the real UI silently lost its
|
|
167
|
-
* graph — the UI sends `blob`, so `body.definition` was always undefined.
|
|
168
|
-
*/
|
|
169
|
-
interface WorkflowRecord {
|
|
170
|
-
id: number;
|
|
171
|
-
name: string;
|
|
172
|
-
description: string | null;
|
|
173
|
-
blob: Record<string, unknown>;
|
|
174
|
-
blobDefinitionVersion: string;
|
|
175
|
-
active: boolean;
|
|
176
|
-
executionMode: string;
|
|
177
|
-
/** Bumped on every update, like the service's revision counter. */
|
|
178
|
-
revision: number;
|
|
179
|
-
buildStatus: string;
|
|
180
|
-
createdAt: string;
|
|
181
|
-
updatedAt: string;
|
|
182
|
-
}
|
|
183
|
-
interface TriggerRecord {
|
|
184
|
-
id: string;
|
|
185
|
-
workflowId: number;
|
|
186
|
-
type: string;
|
|
187
|
-
name: string | null;
|
|
188
|
-
config: Record<string, unknown>;
|
|
189
|
-
active: boolean;
|
|
190
|
-
createdAt: string;
|
|
191
|
-
updatedAt: string;
|
|
192
|
-
}
|
|
193
|
-
/**
|
|
194
|
-
* One entry of the tenant state store (PO-374), flattened across the four
|
|
195
|
-
* roles: `key` is the mapping's left id, the cursor's partition key, the
|
|
196
|
-
* claimed key or the digest's entity key, and `value` the partner id, the
|
|
197
|
-
* watermark, the expiry or the hash.
|
|
198
|
-
*
|
|
199
|
-
* The mock keeps them in one list rather than four tables because nothing here
|
|
200
|
-
* enforces integrity — the real store's constraints are the product, this is a
|
|
201
|
-
* scratchpad that makes a node's second run behave like a second run.
|
|
202
|
-
*/
|
|
203
|
-
interface StateEntryRecord {
|
|
204
|
-
namespace: string;
|
|
205
|
-
role: 'mapping' | 'cursor' | 'dedupe' | 'digest';
|
|
206
|
-
key: string;
|
|
207
|
-
value: unknown;
|
|
208
|
-
updatedAt: string;
|
|
209
|
-
}
|
|
210
|
-
interface DevStoreSnapshot {
|
|
211
|
-
schemaVersion: number;
|
|
212
|
-
credentials: CredentialRecord[];
|
|
213
|
-
secrets: SecretRecord[];
|
|
214
|
-
workflows: WorkflowRecord[];
|
|
215
|
-
triggers: TriggerRecord[];
|
|
216
|
-
stateEntries?: StateEntryRecord[];
|
|
217
|
-
nextWorkflowId: number;
|
|
218
|
-
}
|
|
219
|
-
/**
|
|
220
|
-
* Bumped to 2 when workflows moved from `definition` to the contract's `blob` /
|
|
221
|
-
* `blob_definition_version` / `active` / `execution_mode`, and to 3 when the
|
|
222
|
-
* state store (PO-374) arrived. `loadState` discards an overlay whose version
|
|
223
|
-
* does not match, which is the migration: seeds are the source of truth, the
|
|
224
|
-
* overlay is disposable session state.
|
|
225
|
-
*/
|
|
226
|
-
declare const STORE_SCHEMA_VERSION = 3;
|
|
227
|
-
declare class DevStore {
|
|
228
|
-
private onChange?;
|
|
229
|
-
private credentials;
|
|
230
|
-
private secrets;
|
|
231
|
-
private workflows;
|
|
232
|
-
private triggers;
|
|
233
|
-
/** Keyed by `${role}\u0000${namespace}\u0000${key}` — a NUL occurs in no part. */
|
|
234
|
-
private stateEntries;
|
|
235
|
-
private nextWorkflowId;
|
|
236
|
-
/**
|
|
237
|
-
* @param onChange fired after any mutation so a caller (the CLI) can persist
|
|
238
|
-
* the session to `.revenexx-dev/state.json`.
|
|
239
|
-
*/
|
|
240
|
-
constructor(onChange?: (() => void) | undefined);
|
|
241
|
-
/** (Re)wire the post-mutation callback — e.g. attach it only after seeding. */
|
|
242
|
-
setOnMutation(onChange: (() => void) | undefined): void;
|
|
243
|
-
private touch;
|
|
244
|
-
listCredentials(typeSlug?: string): CredentialRecord[];
|
|
245
|
-
getCredential(id: string): CredentialRecord | undefined;
|
|
246
|
-
createCredential(input: {
|
|
247
|
-
credentialTypeSlug: string;
|
|
248
|
-
name: string;
|
|
249
|
-
config: Record<string, unknown>;
|
|
250
|
-
status?: string;
|
|
251
|
-
/** Stable id — pass to keep a seeded credential's id fixed across restarts. */
|
|
252
|
-
id?: string;
|
|
253
|
-
durableCreds?: Record<string, unknown> | null;
|
|
254
|
-
}): CredentialRecord;
|
|
255
|
-
updateCredential(id: string, patch: Partial<Pick<CredentialRecord, 'name' | 'config' | 'status' | 'durableCreds'>>): CredentialRecord | undefined;
|
|
256
|
-
/**
|
|
257
|
-
* Records the outcome of a credential test. The service persists this on the
|
|
258
|
-
* record and reports it back from `POST /credentials/{id}/test`.
|
|
259
|
-
*/
|
|
260
|
-
recordCredentialTest(id: string, result: {
|
|
261
|
-
ok: boolean;
|
|
262
|
-
message?: string | null;
|
|
263
|
-
}): CredentialRecord | undefined;
|
|
264
|
-
deleteCredential(id: string): boolean;
|
|
265
|
-
listSecrets(): SecretRecord[];
|
|
266
|
-
getSecret(key: string): SecretRecord | undefined;
|
|
267
|
-
setSecret(key: string, value: string): SecretRecord;
|
|
268
|
-
deleteSecret(key: string): boolean;
|
|
269
|
-
listWorkflows(): WorkflowRecord[];
|
|
270
|
-
getWorkflow(id: number): WorkflowRecord | undefined;
|
|
271
|
-
createWorkflow(input: {
|
|
272
|
-
name: string;
|
|
273
|
-
blob: Record<string, unknown>;
|
|
274
|
-
blobDefinitionVersion?: string;
|
|
275
|
-
description?: string | null;
|
|
276
|
-
active?: boolean;
|
|
277
|
-
executionMode?: string;
|
|
278
|
-
}): WorkflowRecord;
|
|
279
|
-
updateWorkflow(id: number, patch: Partial<Pick<WorkflowRecord, 'name' | 'description' | 'blob' | 'blobDefinitionVersion' | 'active' | 'executionMode' | 'buildStatus'>>): WorkflowRecord | undefined;
|
|
280
|
-
deleteWorkflow(id: number): boolean;
|
|
281
|
-
listTriggers(workflowId: number): TriggerRecord[];
|
|
282
|
-
getTrigger(id: string): TriggerRecord | undefined;
|
|
283
|
-
createTrigger(input: {
|
|
284
|
-
workflowId: number;
|
|
285
|
-
type: string;
|
|
286
|
-
name?: string | null;
|
|
287
|
-
config?: Record<string, unknown>;
|
|
288
|
-
active?: boolean;
|
|
289
|
-
id?: string;
|
|
290
|
-
}): TriggerRecord;
|
|
291
|
-
replaceTrigger(id: string, input: {
|
|
292
|
-
type: string;
|
|
293
|
-
name?: string | null;
|
|
294
|
-
config?: Record<string, unknown>;
|
|
295
|
-
active?: boolean;
|
|
296
|
-
}): TriggerRecord | undefined;
|
|
297
|
-
deleteTrigger(id: string): boolean;
|
|
298
|
-
/** The stored entry for a role/namespace/key, or undefined when unknown. */
|
|
299
|
-
getStateEntry(role: StateEntryRecord['role'], namespace: string, key: string): StateEntryRecord | undefined;
|
|
300
|
-
/** Every entry a namespace holds in one role — how a reverse mapping lookup is answered. */
|
|
301
|
-
listStateEntries(role: StateEntryRecord['role'], namespace: string): StateEntryRecord[];
|
|
302
|
-
putStateEntry(entry: Omit<StateEntryRecord, 'updatedAt'>): StateEntryRecord;
|
|
303
|
-
toSnapshot(): DevStoreSnapshot;
|
|
304
|
-
loadSnapshot(snapshot: DevStoreSnapshot): void;
|
|
305
|
-
/**
|
|
306
|
-
* Overlays a snapshot on top of the current contents (upsert by id/key), used
|
|
307
|
-
* to layer the persisted `.revenexx-dev/state.json` session over the freshly
|
|
308
|
-
* applied committed seeds. State entries win over seed entries with the same
|
|
309
|
-
* id/key; seed-only entries are preserved.
|
|
310
|
-
*/
|
|
311
|
-
mergeSnapshot(snapshot: DevStoreSnapshot): void;
|
|
312
|
-
}
|
|
313
|
-
|
|
314
|
-
/**
|
|
315
|
-
* Layered persistence for the preview session:
|
|
316
|
-
* 1. committed seeds (this module's {@link applySeeds}) — the durable base,
|
|
317
|
-
* with `${ENV_VAR}` references interpolated from the environment;
|
|
318
|
-
* 2. `.revenexx-dev/state.json` overlay ({@link loadState}/{@link saveState}) —
|
|
319
|
-
* interactive session state, versioned and disposable.
|
|
320
|
-
*/
|
|
321
|
-
interface CredentialSeed {
|
|
322
|
-
credentialTypeSlug: string;
|
|
323
|
-
name: string;
|
|
324
|
-
config: Record<string, unknown>;
|
|
325
|
-
/** Stable id so workflows can reference the credential across restarts. */
|
|
326
|
-
id?: string;
|
|
327
|
-
status?: string;
|
|
328
|
-
durableCreds?: Record<string, unknown> | null;
|
|
329
|
-
}
|
|
330
|
-
interface SecretSeed {
|
|
331
|
-
key: string;
|
|
332
|
-
value: string;
|
|
333
|
-
}
|
|
334
|
-
interface WorkflowSeed {
|
|
335
|
-
name: string;
|
|
336
|
-
/** The workflow graph, named as the service names it. */
|
|
337
|
-
blob?: Record<string, unknown>;
|
|
338
|
-
/**
|
|
339
|
-
* @deprecated The mock called this `definition` before it was aligned to the
|
|
340
|
-
* service contract. Still accepted so existing seed files keep working.
|
|
341
|
-
*/
|
|
342
|
-
definition?: Record<string, unknown>;
|
|
343
|
-
description?: string | null;
|
|
344
|
-
active?: boolean;
|
|
345
|
-
executionMode?: string;
|
|
346
|
-
}
|
|
347
|
-
interface DevSeeds {
|
|
348
|
-
credentials?: CredentialSeed[];
|
|
349
|
-
secrets?: SecretSeed[];
|
|
350
|
-
workflows?: WorkflowSeed[];
|
|
351
|
-
}
|
|
352
|
-
/**
|
|
353
|
-
* Recursively replaces `${ENV_VAR}` references in string values from `env`.
|
|
354
|
-
* Throws a clear error when a referenced variable is unset so a developer
|
|
355
|
-
* knows to add it to their `.env` — keeping secrets out of committed seeds.
|
|
356
|
-
*/
|
|
357
|
-
declare function interpolateEnv<T>(value: T, env?: NodeJS.ProcessEnv): T;
|
|
358
|
-
/** Applies committed seeds to the store (env-interpolated). */
|
|
359
|
-
declare function applySeeds(store: DevStore, seeds: DevSeeds, env?: NodeJS.ProcessEnv): void;
|
|
360
|
-
/**
|
|
361
|
-
* Reads a persisted session snapshot. Returns `null` (and warns) when the file
|
|
362
|
-
* is absent or its `schemaVersion` no longer matches — the overlay is
|
|
363
|
-
* disposable, so a mismatch is discarded rather than migrated.
|
|
364
|
-
*/
|
|
365
|
-
declare function loadState(file: string, log?: (msg: string) => void): DevStoreSnapshot | null;
|
|
366
|
-
declare function saveState(file: string, snapshot: DevStoreSnapshot): void;
|
|
367
|
-
/**
|
|
368
|
-
* Loads committed seeds from a directory (default `dev/seeds`). Resolves the
|
|
369
|
-
* first present entry file and reads its `default` or named `seeds` export.
|
|
370
|
-
* Returns empty seeds when no seed directory/entry exists.
|
|
371
|
-
*/
|
|
372
|
-
declare function loadSeedsFromDir(dir: string): Promise<DevSeeds>;
|
|
373
|
-
|
|
374
|
-
declare function nodeVersions(loaded: LoadedPackage, slug: string): string[];
|
|
375
|
-
/**
|
|
376
|
-
* The order `GET /nodes` lists a package's nodes in: every version of a slug
|
|
377
|
-
* together, newest first, with the slugs themselves in the order the package
|
|
378
|
-
* exports them.
|
|
379
|
-
*
|
|
380
|
-
* Export order alone is not enough any more. The registry answers each slug's
|
|
381
|
-
* versions semver-descending, and the studio's catalogue takes that order as
|
|
382
|
-
* given rather than parsing a semver of its own — since
|
|
383
|
-
* `@revenexx/studio-integrations` 1.3.0 `newerExecutableVersions()` reads "newer
|
|
384
|
-
* than the pinned one" as "earlier in this array". A package that exports 1.0.0
|
|
385
|
-
* before 2.0.0 — the order a human writes them in — would therefore have the
|
|
386
|
-
* inspector announce the OLDER version as the upgrade, and say nothing about the
|
|
387
|
-
* real one. `GET /nodes/{slug}/versions` has always sorted; this is the same
|
|
388
|
-
* order on the listing the catalogue is actually built from.
|
|
389
|
-
*/
|
|
390
|
-
declare function listNodesNewestFirst(nodes: readonly INodeDescription[]): INodeDescription[];
|
|
391
|
-
declare function findNode(loaded: LoadedPackage, slug: string, version?: string): INode;
|
|
392
|
-
declare function findCredential(loaded: LoadedPackage, slug: string): ICredential;
|
|
393
|
-
declare function findCredentialType(loaded: LoadedPackage, slug: string): ICredentialDescription;
|
|
394
|
-
/** Resolves a credential instance's access data by running its real `resolve`. */
|
|
395
|
-
declare function resolveCredentialInstance(loaded: LoadedPackage, store: DevStore, credentialId: string): Promise<ICredentialResolveResult>;
|
|
396
|
-
interface ResolveNodeConfigInput {
|
|
397
|
-
slug: string;
|
|
398
|
-
version?: string;
|
|
399
|
-
/** `"*"` (all), `"outputs"`, or a specific config field key. */
|
|
400
|
-
target: string;
|
|
401
|
-
config: Record<string, unknown>;
|
|
402
|
-
locale?: string;
|
|
403
|
-
}
|
|
404
|
-
interface ResolveNodeConfigResult {
|
|
405
|
-
options?: IConfigOption[];
|
|
406
|
-
fields?: IConfigField[];
|
|
407
|
-
outputs?: IOutputPort[];
|
|
408
|
-
}
|
|
409
|
-
/**
|
|
410
|
-
* Runs a node's author-time resolvers for the requested `target`, mirroring
|
|
411
|
-
* the server's `config:resolve` semantics.
|
|
412
|
-
*/
|
|
413
|
-
declare function resolveNodeConfig(loaded: LoadedPackage, store: DevStore, input: ResolveNodeConfigInput): Promise<ResolveNodeConfigResult>;
|
|
414
|
-
interface ValidateNodeConfigInput {
|
|
415
|
-
slug: string;
|
|
416
|
-
version?: string;
|
|
417
|
-
config: Record<string, unknown>;
|
|
418
|
-
locale?: string;
|
|
419
|
-
}
|
|
420
|
-
interface ValidateNodeConfigResult {
|
|
421
|
-
valid: boolean;
|
|
422
|
-
/** Config field key → human-readable messages. Empty object when valid. */
|
|
423
|
-
errors: Record<string, string[]>;
|
|
424
|
-
}
|
|
425
|
-
/**
|
|
426
|
-
* Validates a submitted node `config` against the field rules in its manifest
|
|
427
|
-
* (`required`, `IConfigValidation`, types, static options). For `dynamic-schema`
|
|
428
|
-
* fields the resolved child schema is fetched and its rules applied to the
|
|
429
|
-
* flattened keys. Deep cross-field validation is intentionally out of scope
|
|
430
|
-
* (the production service does that on save); this mirrors the mock's
|
|
431
|
-
* "light, schema-based" fidelity. Unknown extra keys are ignored.
|
|
432
|
-
*
|
|
433
|
-
* A field whose `showIf` does not hold (SDK 1.0.0, PO-410) is skipped whole —
|
|
434
|
-
* not demanded when required, and not type-checked either. The editor does not
|
|
435
|
-
* draw it, so whatever is left under its key is a leftover from a choice the
|
|
436
|
-
* author has since changed, and refusing to save because of it would leave them
|
|
437
|
-
* with an error against a field they cannot see. `settingApplies` comes from the
|
|
438
|
-
* SDK rather than being re-implemented here: the editor drawing the field and
|
|
439
|
-
* this validator deciding whether to demand it have to agree word for word.
|
|
440
|
-
*/
|
|
441
|
-
declare function validateNodeConfig(loaded: LoadedPackage, store: DevStore, input: ValidateNodeConfigInput): Promise<ValidateNodeConfigResult>;
|
|
442
|
-
/** Runs a credential type's `test` against inline (unsaved) config. */
|
|
443
|
-
declare function testCredentialConfig(loaded: LoadedPackage, store: DevStore, typeSlug: string, config: Record<string, unknown>): Promise<ICredentialTestResult>;
|
|
444
|
-
/** Runs `test` against a saved credential instance's stored config. */
|
|
445
|
-
declare function testCredentialInstance(loaded: LoadedPackage, store: DevStore, credentialId: string): Promise<ICredentialTestResult>;
|
|
446
|
-
declare function buildOAuthAuthorizeUrl(loaded: LoadedPackage, store: DevStore, credentialId: string, params: {
|
|
447
|
-
redirectUri: string;
|
|
448
|
-
state: string;
|
|
449
|
-
}): Promise<{
|
|
450
|
-
authorizeUrl: string;
|
|
451
|
-
codeVerifier?: string;
|
|
452
|
-
}>;
|
|
453
|
-
declare function exchangeOAuthCode(loaded: LoadedPackage, store: DevStore, credentialId: string, params: {
|
|
454
|
-
code: string;
|
|
455
|
-
redirectUri: string;
|
|
456
|
-
codeVerifier?: string;
|
|
457
|
-
}): Promise<{
|
|
458
|
-
durableCreds: Record<string, unknown>;
|
|
459
|
-
}>;
|
|
460
|
-
|
|
461
|
-
interface DevServerDeps {
|
|
462
|
-
/** Returns the currently-loaded package; a function so hot-reload can swap it. */
|
|
463
|
-
getPackage(): LoadedPackage;
|
|
464
|
-
store: DevStore;
|
|
465
|
-
/** JSON schemas served at `/schemas/{domain}[/{version}]`, keyed by `domain` and `domain/version`. */
|
|
466
|
-
schemas?: Record<string, unknown>;
|
|
467
|
-
}
|
|
468
|
-
/** Builds the `(req, res)` request listener implementing the mock `/api/v1` surface. */
|
|
469
|
-
declare function createRequestListener(deps: DevServerDeps): http.RequestListener;
|
|
470
|
-
declare function createDevServer(deps: DevServerDeps): http.Server;
|
|
471
|
-
|
|
472
1
|
/**
|
|
473
2
|
* `@revenexx/integrations-node-devkit` — local development kit for Revenexx
|
|
474
3
|
* integration node packages. Dev/CI only; never bundled into a node package.
|
|
@@ -477,6 +6,11 @@ declare function createDevServer(deps: DevServerDeps): http.Server;
|
|
|
477
6
|
* - `@revenexx/integrations-node-devkit` → the mock-API preview server (this entry)
|
|
478
7
|
* - `@revenexx/integrations-node-devkit/testing` → the unit-testing harness
|
|
479
8
|
*/
|
|
480
|
-
declare const DEVKIT_VERSION: string;
|
|
481
|
-
|
|
482
|
-
export {
|
|
9
|
+
export declare const DEVKIT_VERSION: string;
|
|
10
|
+
export { ENV_FILE_MIN_NODE, type EnvFileChoice, loadEnvFile, type LoadEnvFileOptions, nodeOwnedEnvFlag, resolveEnvFile, } from './env.js';
|
|
11
|
+
export { DevApiError } from './errors.js';
|
|
12
|
+
export { ensureTsxRegistered, importFresh, type LoadedPackage, loadPackageFromEntry, resolveExports, } from './loader.js';
|
|
13
|
+
export { applySeeds, type CredentialSeed, type DevSeeds, interpolateEnv, loadSeedsFromDir, loadState, saveState, type SecretSeed, type WorkflowSeed, } from './persistence.js';
|
|
14
|
+
export { buildOAuthAuthorizeUrl, exchangeOAuthCode, findCredential, findCredentialType, findNode, listNodesNewestFirst, nodeVersions, type ResolveNodeConfigInput, type ResolveNodeConfigResult, resolveCredentialInstance, resolveNodeConfig, testCredentialConfig, testCredentialInstance, type ValidateNodeConfigInput, type ValidateNodeConfigResult, validateNodeConfig, } from './resolve.js';
|
|
15
|
+
export { createDevServer, createRequestListener, type DevServerDeps, } from './server.js';
|
|
16
|
+
export { type CredentialRecord, DEV_TENANT_ID, DevStore, type DevStoreSnapshot, type SecretRecord, STORE_SCHEMA_VERSION, type TriggerRecord, type WorkflowRecord, } from './store.js';
|
package/dist/loader.d.ts
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import { type ICredential, type INode, type ITemplateDescription, type NodeManifest } from '@revenexx/integrations-node-sdk';
|
|
2
|
+
/** Identity of the npm package the nodes came from, as `GET /nodes` reports it. */
|
|
3
|
+
export interface PackageInfo {
|
|
4
|
+
name: string;
|
|
5
|
+
version: string;
|
|
6
|
+
label: string;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* A node package loaded into the dev process: its live `NODES` / `CREDENTIALS`
|
|
10
|
+
* / `TEMPLATES` instances (so author-time resolvers, `test`, and `resolve` can
|
|
11
|
+
* be invoked in-process — no bundle, no sandbox) plus the derived manifest the
|
|
12
|
+
* mock API serves.
|
|
13
|
+
*/
|
|
14
|
+
export interface LoadedPackage {
|
|
15
|
+
nodes: INode[];
|
|
16
|
+
credentials: ICredential[];
|
|
17
|
+
templates: ITemplateDescription[];
|
|
18
|
+
manifest: NodeManifest;
|
|
19
|
+
/** Reported as each node's `package`; the contract declares it non-null. */
|
|
20
|
+
packageInfo: PackageInfo;
|
|
21
|
+
/** Stands in for the service's per-node `created_at`/`updated_at`. */
|
|
22
|
+
loadedAt: string;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Reads the nearest `package.json` above `entryPath` for the node package's
|
|
26
|
+
* identity. The real service knows this from the published bundle; here it comes
|
|
27
|
+
* from the developer's own manifest.
|
|
28
|
+
*/
|
|
29
|
+
export declare function readPackageInfo(entryPath: string): PackageInfo;
|
|
30
|
+
interface PackageExports {
|
|
31
|
+
NODES?: unknown;
|
|
32
|
+
CREDENTIALS?: unknown;
|
|
33
|
+
TEMPLATES?: unknown;
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* Validates a package's module exports and builds a {@link LoadedPackage}.
|
|
37
|
+
* Mirrors the checks in the SDK's `rvnxx-nodes manifest` CLI so the dev loop
|
|
38
|
+
* and the build produce identical manifests.
|
|
39
|
+
*/
|
|
40
|
+
export declare function resolveExports(mod: PackageExports, packageInfo?: PackageInfo): LoadedPackage;
|
|
41
|
+
/**
|
|
42
|
+
* Registers the `tsx` ESM loader once per process so `import()` can load
|
|
43
|
+
* TypeScript sources directly. Idempotent.
|
|
44
|
+
*/
|
|
45
|
+
export declare function ensureTsxRegistered(): Promise<void>;
|
|
46
|
+
/** True when a changed file is package source the mock should reload for. */
|
|
47
|
+
export declare function isReloadableSource(file: string): boolean;
|
|
48
|
+
/** Imports a module by path, registering tsx first for TypeScript sources. */
|
|
49
|
+
export declare function importFresh<T = unknown>(entryPath: string): Promise<T>;
|
|
50
|
+
/**
|
|
51
|
+
* Imports a package entry and resolves its exports. Supports TypeScript
|
|
52
|
+
* sources directly (via `tsx`) so the preview runs against the developer's
|
|
53
|
+
* live `src/`, not a built artifact. A cache-busting query is appended so
|
|
54
|
+
* repeated calls (hot-reload) re-evaluate the module.
|
|
55
|
+
*/
|
|
56
|
+
export declare function loadPackageFromEntry(entryPath: string): Promise<LoadedPackage>;
|
|
57
|
+
export {};
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import { type DevStore, type DevStoreSnapshot } from './store.js';
|
|
2
|
+
/**
|
|
3
|
+
* Layered persistence for the preview session:
|
|
4
|
+
* 1. committed seeds (this module's {@link applySeeds}) — the durable base,
|
|
5
|
+
* with `${ENV_VAR}` references interpolated from the environment;
|
|
6
|
+
* 2. `.revenexx-dev/state.json` overlay ({@link loadState}/{@link saveState}) —
|
|
7
|
+
* interactive session state, versioned and disposable.
|
|
8
|
+
*/
|
|
9
|
+
export interface CredentialSeed {
|
|
10
|
+
credentialTypeSlug: string;
|
|
11
|
+
name: string;
|
|
12
|
+
config: Record<string, unknown>;
|
|
13
|
+
/** Stable id so workflows can reference the credential across restarts. */
|
|
14
|
+
id?: string;
|
|
15
|
+
status?: string;
|
|
16
|
+
durableCreds?: Record<string, unknown> | null;
|
|
17
|
+
}
|
|
18
|
+
export interface SecretSeed {
|
|
19
|
+
key: string;
|
|
20
|
+
value: string;
|
|
21
|
+
}
|
|
22
|
+
export interface WorkflowSeed {
|
|
23
|
+
name: string;
|
|
24
|
+
/** The workflow graph, named as the service names it. */
|
|
25
|
+
blob?: Record<string, unknown>;
|
|
26
|
+
/**
|
|
27
|
+
* @deprecated The mock called this `definition` before it was aligned to the
|
|
28
|
+
* service contract. Still accepted so existing seed files keep working.
|
|
29
|
+
*/
|
|
30
|
+
definition?: Record<string, unknown>;
|
|
31
|
+
description?: string | null;
|
|
32
|
+
active?: boolean;
|
|
33
|
+
executionMode?: string;
|
|
34
|
+
}
|
|
35
|
+
export interface DevSeeds {
|
|
36
|
+
credentials?: CredentialSeed[];
|
|
37
|
+
secrets?: SecretSeed[];
|
|
38
|
+
workflows?: WorkflowSeed[];
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Recursively replaces `${ENV_VAR}` references in string values from `env`.
|
|
42
|
+
* Throws a clear error when a referenced variable is unset so a developer
|
|
43
|
+
* knows to add it to their `.env` — keeping secrets out of committed seeds.
|
|
44
|
+
*/
|
|
45
|
+
export declare function interpolateEnv<T>(value: T, env?: NodeJS.ProcessEnv): T;
|
|
46
|
+
/** Applies committed seeds to the store (env-interpolated). */
|
|
47
|
+
export declare function applySeeds(store: DevStore, seeds: DevSeeds, env?: NodeJS.ProcessEnv): void;
|
|
48
|
+
/**
|
|
49
|
+
* Reads a persisted session snapshot. Returns `null` (and warns) when the file
|
|
50
|
+
* is absent or its `schemaVersion` no longer matches — the overlay is
|
|
51
|
+
* disposable, so a mismatch is discarded rather than migrated.
|
|
52
|
+
*/
|
|
53
|
+
export declare function loadState(file: string, log?: (msg: string) => void): DevStoreSnapshot | null;
|
|
54
|
+
export declare function saveState(file: string, snapshot: DevStoreSnapshot): void;
|
|
55
|
+
/**
|
|
56
|
+
* Loads committed seeds from a directory (default `dev/seeds`). Resolves the
|
|
57
|
+
* first present entry file and reads its `default` or named `seeds` export.
|
|
58
|
+
* Returns empty seeds when no seed directory/entry exists.
|
|
59
|
+
*/
|
|
60
|
+
export declare function loadSeedsFromDir(dir: string): Promise<DevSeeds>;
|
package/dist/ports.d.ts
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import type { Server } from 'node:http';
|
|
2
|
+
export interface ListenOptions {
|
|
3
|
+
port: number;
|
|
4
|
+
/** True when the port was named explicitly (`--port` / `$PORT`): never relocate. */
|
|
5
|
+
strict: boolean;
|
|
6
|
+
limit?: number;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* Binds `server`, walking up from `options.port` on `EADDRINUSE`. Resolves with the
|
|
10
|
+
* port actually bound — callers must use that value rather than the one they asked
|
|
11
|
+
* for, since every URL they print or hand to a child process depends on it.
|
|
12
|
+
*/
|
|
13
|
+
export declare function listenWithFallback(server: Server, options: ListenOptions): Promise<number>;
|
|
14
|
+
/**
|
|
15
|
+
* First free port at or above `base`, found by binding a throwaway listener.
|
|
16
|
+
*
|
|
17
|
+
* For ports someone else will bind — the Nuxt dev server runs as a child process.
|
|
18
|
+
* The gap between this check and that bind is a real (if narrow) race; Nuxt's own
|
|
19
|
+
* listhen fallback covers it, which is why devkit no longer prints the UI URL
|
|
20
|
+
* itself and lets Nuxt announce the port it truly got.
|
|
21
|
+
*/
|
|
22
|
+
export declare function findFreePort(base: number, limit?: number): Promise<number>;
|
|
23
|
+
/** Parses a `--port` value, rejecting what would otherwise reach `listen()` as NaN. */
|
|
24
|
+
export declare function parsePort(value: string | undefined, flag: string): number;
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
export interface PreviewChildEnvOptions {
|
|
2
|
+
/** Usually `process.env`. */
|
|
3
|
+
base: NodeJS.ProcessEnv;
|
|
4
|
+
/** Mock API base URL, including the port actually bound. */
|
|
5
|
+
apiUrl: string;
|
|
6
|
+
/** Per-repo Nuxt build directory (`hostBuildDir`). */
|
|
7
|
+
buildDir: string;
|
|
8
|
+
/** Per-repo Vite dependency cache (`hostViteCacheDir`). */
|
|
9
|
+
viteCacheDir: string;
|
|
10
|
+
/** Port the Nuxt dev server should listen on. */
|
|
11
|
+
uiPort: number;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Environment for the `nuxt dev` child process.
|
|
15
|
+
*
|
|
16
|
+
* A pure function because the three things it gets right are all invisible at a
|
|
17
|
+
* glance, and each of them was a bug:
|
|
18
|
+
*
|
|
19
|
+
* - **`PORT` is deleted.** It is the mock's variable, but Nuxt's listhen reads it
|
|
20
|
+
* too, so `PORT=4000 integrations-devkit preview` used to have the mock *and*
|
|
21
|
+
* the UI both claim 4000. Nuxt then relocated silently and every URL devkit
|
|
22
|
+
* printed was wrong. `NUXT_PORT` outranks `PORT` anyway; deleting it as well
|
|
23
|
+
* keeps the mock's port out of the child's namespace entirely.
|
|
24
|
+
* - **`DEVKIT_VITE_CACHE_DIR` is set.** Without it Vite's dependency cache lands
|
|
25
|
+
* in the *shared* host's `node_modules/.cache/vite`, and since Vite's config
|
|
26
|
+
* hash includes the `#build` alias — i.e. the per-repo build dir — two repos
|
|
27
|
+
* each consider the other's cache stale and `rm -rf` it while it is being
|
|
28
|
+
* served from. Per-repo build dirs alone actively caused that.
|
|
29
|
+
* - **`NUXT_PORT` is set explicitly**, so devkit knows the UI port instead of
|
|
30
|
+
* guessing 3000 and hoping listhen agreed.
|
|
31
|
+
*/
|
|
32
|
+
export declare function previewChildEnv(options: PreviewChildEnvOptions): NodeJS.ProcessEnv;
|