@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/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 { type CredentialRecord, type CredentialSeed, DEVKIT_VERSION, DEV_TENANT_ID, DevApiError, type DevSeeds, type DevServerDeps, DevStore, type DevStoreSnapshot, ENV_FILE_MIN_NODE, type EnvFileChoice, type LoadEnvFileOptions, type LoadedPackage, type ResolveNodeConfigInput, type ResolveNodeConfigResult, STORE_SCHEMA_VERSION, type SecretRecord, type SecretSeed, type TriggerRecord, type ValidateNodeConfigInput, type ValidateNodeConfigResult, type WorkflowRecord, type WorkflowSeed, applySeeds, buildOAuthAuthorizeUrl, createDevServer, createRequestListener, ensureTsxRegistered, exchangeOAuthCode, findCredential, findCredentialType, findNode, importFresh, interpolateEnv, listNodesNewestFirst, loadEnvFile, loadPackageFromEntry, loadSeedsFromDir, loadState, nodeOwnedEnvFlag, nodeVersions, resolveCredentialInstance, resolveEnvFile, resolveExports, resolveNodeConfig, saveState, testCredentialConfig, testCredentialInstance, validateNodeConfig };
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';
@@ -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>;
@@ -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;