@attraccess/plugins-backend-sdk 1.9.0 → 1.11.0-beta.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/package.json +8 -3
- package/src/index.d.ts +8 -0
- package/src/index.js +8 -0
- package/src/index.js.map +1 -1
- package/src/lib/auth-decorator.d.ts +4 -0
- package/src/lib/auth-decorator.js +20 -5
- package/src/lib/auth-decorator.js.map +1 -1
- package/src/lib/auth.types.d.ts +2 -0
- package/src/lib/mqtt-credential-provisioning.d.ts +52 -0
- package/src/lib/mqtt-credential-provisioning.js +5 -0
- package/src/lib/mqtt-credential-provisioning.js.map +1 -0
- package/src/lib/plugin-audit.d.ts +94 -0
- package/src/lib/plugin-audit.js +170 -0
- package/src/lib/plugin-audit.js.map +1 -0
- package/src/lib/plugin-backend-module.d.ts +66 -0
- package/src/lib/plugin-backend-module.js +3 -0
- package/src/lib/plugin-backend-module.js.map +1 -0
- package/src/lib/plugin-context.d.ts +109 -33
- package/src/lib/plugin-context.js +6 -6
- package/src/lib/plugin-context.js.map +1 -1
- package/src/lib/plugin-flow-node.d.ts +172 -0
- package/src/lib/plugin-flow-node.js +12 -0
- package/src/lib/plugin-flow-node.js.map +1 -0
- package/src/lib/plugin-live-updates.d.ts +21 -0
- package/src/lib/plugin-live-updates.js +3 -0
- package/src/lib/plugin-live-updates.js.map +1 -0
- package/src/lib/plugin-notifications.d.ts +83 -0
- package/src/lib/plugin-notifications.js +3 -0
- package/src/lib/plugin-notifications.js.map +1 -0
- package/src/lib/plugin-resource-access.d.ts +89 -0
- package/src/lib/plugin-resource-access.js +3 -0
- package/src/lib/plugin-resource-access.js.map +1 -0
- package/src/lib/plugin.interface.d.ts +78 -5
- package/src/lib/plugin.interface.js +26 -1
- package/src/lib/plugin.interface.js.map +1 -1
- package/src/lib/reader-ui.d.ts +317 -0
- package/src/lib/reader-ui.js +115 -0
- package/src/lib/reader-ui.js.map +1 -0
- package/src/lib/shared-live-sampler.d.ts +11 -0
- package/src/lib/shared-live-sampler.js +33 -0
- package/src/lib/shared-live-sampler.js.map +1 -0
|
@@ -1,23 +1,13 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { LoggerService, Type } from '@nestjs/common';
|
|
2
2
|
import { EventEmitter2 } from '@nestjs/event-emitter';
|
|
3
|
-
import { DataSource, EntityTarget, ObjectLiteral, Repository } from 'typeorm';
|
|
3
|
+
import { DataSource, EntityManager, EntityTarget, ObjectLiteral, Repository } from 'typeorm';
|
|
4
|
+
import type { MqttCredentialProvisioningHostProvider } from './mqtt-credential-provisioning';
|
|
5
|
+
import type { PluginAuditContext } from './plugin-audit';
|
|
6
|
+
import type { PluginReaderUiApi, PluginStartBlockedApi } from './reader-ui';
|
|
7
|
+
import type { PluginNotificationsContext } from './plugin-notifications';
|
|
8
|
+
import type { PluginResourceAccessContext } from './plugin-resource-access';
|
|
9
|
+
import type { PluginLiveUpdatesContext } from './plugin-live-updates';
|
|
4
10
|
import { SystemEvent, SystemEventHandler, SystemEventPayload, SystemEventSubscription } from './plugin.interface';
|
|
5
|
-
import type { PluginEntityClass } from './entity';
|
|
6
|
-
/**
|
|
7
|
-
* DI token under which a plugin's own services can inject the PluginContext.
|
|
8
|
-
* The host publishes the context as a module-scoped provider with this token.
|
|
9
|
-
*/
|
|
10
|
-
export declare const PLUGIN_CONTEXT: unique symbol;
|
|
11
|
-
/**
|
|
12
|
-
* Subset of the host manifest exposed to a plugin at runtime. The host's
|
|
13
|
-
* LoadedPluginManifest structurally satisfies this shape.
|
|
14
|
-
*/
|
|
15
|
-
export interface PluginManifestInfo {
|
|
16
|
-
readonly id: string;
|
|
17
|
-
readonly name: string;
|
|
18
|
-
readonly version: string;
|
|
19
|
-
readonly pluginDirectory: string;
|
|
20
|
-
}
|
|
21
11
|
/**
|
|
22
12
|
* DI token under which the host registers its MqttServerHostProvider
|
|
23
13
|
* implementation. The plugin context resolves the provider through this token;
|
|
@@ -34,7 +24,14 @@ export interface MqttServerConnectionConfig {
|
|
|
34
24
|
readonly name: string;
|
|
35
25
|
readonly host: string;
|
|
36
26
|
readonly port: number;
|
|
27
|
+
/** Management API port on the same host (1-65535). Null/omitted uses the provider default. */
|
|
28
|
+
readonly managementPort?: number | null;
|
|
37
29
|
readonly useTls: boolean;
|
|
30
|
+
/** PEM trust anchors for private PKI. Omitted by older hosts. */
|
|
31
|
+
readonly caCert?: string | null;
|
|
32
|
+
/** Integrations requiring authenticated TLS must reject this setting. */
|
|
33
|
+
readonly tlsInsecure?: boolean;
|
|
34
|
+
readonly tlsServername?: string | null;
|
|
38
35
|
readonly username: string | null;
|
|
39
36
|
/** Resolved (decrypted) password. Only ever provided to permitted plugins. */
|
|
40
37
|
readonly password: string | null;
|
|
@@ -49,12 +46,80 @@ export interface MqttServerConnectionConfig {
|
|
|
49
46
|
export interface MqttServerHostProvider {
|
|
50
47
|
getServerConfig(serverId: number): Promise<MqttServerConnectionConfig | null>;
|
|
51
48
|
}
|
|
49
|
+
/** A message delivered to a plugin's MQTT subscription. */
|
|
50
|
+
export interface PluginMqttMessage {
|
|
51
|
+
readonly serverId: number;
|
|
52
|
+
readonly topic: string;
|
|
53
|
+
readonly payload: Buffer;
|
|
54
|
+
}
|
|
55
|
+
/** Handle returned from an MQTT subscription. */
|
|
56
|
+
export interface PluginMqttSubscription {
|
|
57
|
+
unsubscribe(): void;
|
|
58
|
+
}
|
|
59
|
+
export interface PluginMqttClient {
|
|
60
|
+
/**
|
|
61
|
+
* Subscribe through the host's shared MQTT connection. MQTT wildcards `+`
|
|
62
|
+
* and `#` are supported. Resolves after the broker acknowledges the
|
|
63
|
+
* subscription. Handlers run serially; each subscription buffers up to 100
|
|
64
|
+
* messages and drops new messages while full. The returned handle detaches
|
|
65
|
+
* the handler.
|
|
66
|
+
*/
|
|
67
|
+
subscribe(serverId: number, topicFilter: string, handler: (message: PluginMqttMessage) => void | Promise<void>): Promise<PluginMqttSubscription>;
|
|
68
|
+
/** Publish through the host's shared MQTT connection. */
|
|
69
|
+
publish(serverId: number, topic: string, payload: string | Buffer, options?: {
|
|
70
|
+
qos?: 0 | 1 | 2;
|
|
71
|
+
retain?: boolean;
|
|
72
|
+
}): Promise<void>;
|
|
73
|
+
/** Reconnect using current configured settings and restore shared topic
|
|
74
|
+
* registrations. Optional for compatibility with older host runtimes.
|
|
75
|
+
*/
|
|
76
|
+
refreshConnection?(serverId: number): Promise<void>;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* DI token under which a plugin's own services can inject the PluginContext.
|
|
80
|
+
* The host publishes the context as a module-scoped provider with this token.
|
|
81
|
+
*/
|
|
82
|
+
export declare const PLUGIN_CONTEXT: unique symbol;
|
|
83
|
+
/**
|
|
84
|
+
* Subset of the host manifest exposed to a plugin at runtime. The host's
|
|
85
|
+
* LoadedPluginManifest structurally satisfies this shape.
|
|
86
|
+
*/
|
|
87
|
+
export interface PluginManifestInfo {
|
|
88
|
+
readonly id: string;
|
|
89
|
+
readonly name: string;
|
|
90
|
+
readonly version: string;
|
|
91
|
+
readonly pluginDirectory: string;
|
|
92
|
+
}
|
|
93
|
+
/** Host flow functionality available to plugins with the TRIGGER_FLOWS permission. */
|
|
94
|
+
export interface PluginFlowsContext {
|
|
95
|
+
/**
|
|
96
|
+
* Starts a flow from every persisted trigger node of nodeType whose saved
|
|
97
|
+
* configuration matches the supplied external event.
|
|
98
|
+
*/
|
|
99
|
+
trigger(nodeType: string, matches: (config: Record<string, unknown>, nodeId: string) => boolean, payload: object): Promise<void>;
|
|
100
|
+
}
|
|
101
|
+
/** Host-managed encryption for secret material owned by this plugin. */
|
|
102
|
+
export interface PluginSecretsContext {
|
|
103
|
+
encrypt(plaintext: string): string;
|
|
104
|
+
decrypt(ciphertext: string): string;
|
|
105
|
+
}
|
|
52
106
|
/**
|
|
53
107
|
* Curated facade handed to a backend plugin at load time. It is the single,
|
|
54
108
|
* versioned seam between plugin code and the host application. Adding a field is
|
|
55
109
|
* a minor SDK bump; removing/changing one is a major bump.
|
|
56
110
|
*/
|
|
57
111
|
export interface PluginContext {
|
|
112
|
+
/**
|
|
113
|
+
* Version of the running Attraccess host (the one plugin compatibility is checked against). Optional for hosts
|
|
114
|
+
* predating this field, so a plugin that needs it must handle its absence.
|
|
115
|
+
*/
|
|
116
|
+
readonly hostVersion?: string;
|
|
117
|
+
/** Shared authenticated UI transport. Optional for hosts predating this capability. */
|
|
118
|
+
readonly liveUpdates?: PluginLiveUpdatesContext;
|
|
119
|
+
/** Optional for compatibility with hosts predating generic plugin audit support. */
|
|
120
|
+
readonly audit?: PluginAuditContext;
|
|
121
|
+
/** Reader UI helpers. Guarded getter: throws PluginPermissionError without READER_UI. */
|
|
122
|
+
readonly readerUi?: PluginReaderUiApi;
|
|
58
123
|
/** This plugin's own manifest (name, version, directory, id). */
|
|
59
124
|
readonly manifest: PluginManifestInfo;
|
|
60
125
|
/** Shared application event bus — the same EventEmitter2 instance the host uses. */
|
|
@@ -63,6 +128,8 @@ export interface PluginContext {
|
|
|
63
128
|
readonly dataSource: DataSource;
|
|
64
129
|
/** Scoped logger, prefixed with the plugin name. */
|
|
65
130
|
readonly logger: LoggerService;
|
|
131
|
+
/** Shared MQTT connection access. Requires ACCESS_MQTT_SERVERS. */
|
|
132
|
+
readonly mqtt: PluginMqttClient;
|
|
66
133
|
/** Typed repository accessor over the shared DataSource. */
|
|
67
134
|
getRepository<T extends ObjectLiteral>(entity: EntityTarget<T>): Repository<T>;
|
|
68
135
|
/**
|
|
@@ -86,23 +153,32 @@ export interface PluginContext {
|
|
|
86
153
|
* (decrypted) credentials. Requires the ACCESS_MQTT_SERVERS permission.
|
|
87
154
|
* Returns null when no server with the given id exists. The host performs all
|
|
88
155
|
* credential decryption; the plugin only ever receives the mapped config — it
|
|
89
|
-
* stays broker-agnostic (no
|
|
156
|
+
* stays broker-agnostic (no broker-vendor awareness).
|
|
90
157
|
*/
|
|
91
158
|
getMqttServerConfig(serverId: number): Promise<MqttServerConnectionConfig | null>;
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
*/
|
|
97
|
-
|
|
98
|
-
|
|
159
|
+
/** Discover and use the host-selected broker credential provider. Requires ACCESS_MQTT_SERVERS. */
|
|
160
|
+
getMqttCredentialProvisioning(): MqttCredentialProvisioningHostProvider;
|
|
161
|
+
/** Start matching flows from a plugin-declared trigger node. Requires TRIGGER_FLOWS. */
|
|
162
|
+
readonly flows: PluginFlowsContext;
|
|
163
|
+
/** Encrypt and decrypt this plugin's secret material. Requires MANAGE_SECRETS. */
|
|
164
|
+
readonly secrets: PluginSecretsContext;
|
|
165
|
+
/** Notify users under plugin-declared categories. Requires SEND_NOTIFICATIONS. */
|
|
166
|
+
readonly notifications: PluginNotificationsContext;
|
|
167
|
+
/** Tells the host UI that this plugin's `startBlockedQuery` answer changed. Requires ACCESS_HOOKS. */
|
|
168
|
+
readonly startBlocked: PluginStartBlockedApi;
|
|
169
|
+
/** Read-only authorization, maintenance and session queries. Requires ACCESS_RESOURCES. */
|
|
170
|
+
readonly resourceAccess: PluginResourceAccessContext;
|
|
99
171
|
/**
|
|
100
|
-
*
|
|
101
|
-
*
|
|
102
|
-
*
|
|
103
|
-
*
|
|
104
|
-
*
|
|
105
|
-
* the
|
|
172
|
+
* Run `fn` in a serialized database transaction. Concurrent callers (core lifecycle writes included)
|
|
173
|
+
* run one at a time on SQLite, so check-then-write sequences such as overlap checks are race-free.
|
|
174
|
+
* The transaction commits when `fn` resolves and rolls back when it throws. Requires DATABASE_ACCESS.
|
|
175
|
+
*
|
|
176
|
+
* The queue is shared with every core session start and end, so keep `fn` short and limited to database
|
|
177
|
+
* work through the given manager: no HTTP, MQTT, email or other I/O inside. Do not nest calls: a
|
|
178
|
+
* runSerialized started inside `fn` would wait for `fn` itself, so the host rejects it with an error;
|
|
179
|
+
* pass the manager down instead. Core services that write through the same queue (session start/end)
|
|
180
|
+
* must not be awaited inside `fn` either.
|
|
106
181
|
*/
|
|
107
|
-
|
|
182
|
+
runSerialized<T>(fn: (manager: EntityManager) => Promise<T>): Promise<T>;
|
|
108
183
|
}
|
|
184
|
+
export { PluginBackendModule } from './plugin-backend-module';
|
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.
|
|
4
|
-
/**
|
|
5
|
-
* DI token under which a plugin's own services can inject the PluginContext.
|
|
6
|
-
* The host publishes the context as a module-scoped provider with this token.
|
|
7
|
-
*/
|
|
8
|
-
exports.PLUGIN_CONTEXT = Symbol.for('attraccess.plugin.context');
|
|
3
|
+
exports.PLUGIN_CONTEXT = exports.MQTT_SERVER_HOST_PROVIDER = void 0;
|
|
9
4
|
/**
|
|
10
5
|
* DI token under which the host registers its MqttServerHostProvider
|
|
11
6
|
* implementation. The plugin context resolves the provider through this token;
|
|
12
7
|
* plugins never reference it directly — they call getMqttServerConfig instead.
|
|
13
8
|
*/
|
|
14
9
|
exports.MQTT_SERVER_HOST_PROVIDER = Symbol.for('attraccess.plugin.mqttServerHostProvider');
|
|
10
|
+
/**
|
|
11
|
+
* DI token under which a plugin's own services can inject the PluginContext.
|
|
12
|
+
* The host publishes the context as a module-scoped provider with this token.
|
|
13
|
+
*/
|
|
14
|
+
exports.PLUGIN_CONTEXT = Symbol.for('attraccess.plugin.context');
|
|
15
15
|
//# sourceMappingURL=plugin-context.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"plugin-context.js","sourceRoot":"","sources":["../../../../../libs/plugins-backend-sdk/src/lib/plugin-context.ts"],"names":[],"mappings":";;;
|
|
1
|
+
{"version":3,"file":"plugin-context.js","sourceRoot":"","sources":["../../../../../libs/plugins-backend-sdk/src/lib/plugin-context.ts"],"names":[],"mappings":";;;AAUA;;;;GAIG;AACU,QAAA,yBAAyB,GAAG,MAAM,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;AA4EhG;;;GAGG;AACU,QAAA,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC"}
|
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Contract for backend plugins to register custom flow node types.
|
|
3
|
+
*
|
|
4
|
+
* Usage:
|
|
5
|
+
* export default {
|
|
6
|
+
* register(context) { ... },
|
|
7
|
+
* flowNodes: [demoOnNode, demoOffNode],
|
|
8
|
+
* } satisfies PluginBackendModule;
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* Minimal execution context passed to a plugin node's execute() function.
|
|
12
|
+
* Mirrors the subset of NodeExecutionContext that is useful to plugins;
|
|
13
|
+
* the host satisfies this interface structurally.
|
|
14
|
+
*/
|
|
15
|
+
export interface PluginNodeExecutionContext {
|
|
16
|
+
/**
|
|
17
|
+
* Compile a Handlebars template string against the current payload data.
|
|
18
|
+
* Supports the same template variables as built-in node types
|
|
19
|
+
* ({{resource.id}}, {{payload.*}}, etc.).
|
|
20
|
+
*/
|
|
21
|
+
compileTemplate(template: string, data: object): string;
|
|
22
|
+
/**
|
|
23
|
+
* The resource the run acts on: the node's own resource in a resource flow, the triggering resource in a global
|
|
24
|
+
* flow. `null` (or undefined) when the run was not started by a resource event.
|
|
25
|
+
*/
|
|
26
|
+
readonly resourceId?: number | null;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* The kinds of flow a node can be used in: a flow bound to one resource, or a global flow that reacts to
|
|
30
|
+
* events of every resource.
|
|
31
|
+
*/
|
|
32
|
+
export type PluginFlowScope = 'resource' | 'global';
|
|
33
|
+
/** Context passed to `resolveConfigSchema` while the editor or the canvas asks for a node's schema. */
|
|
34
|
+
export interface PluginFlowNodeSchemaContext {
|
|
35
|
+
/** The kind of flow that contains the node. */
|
|
36
|
+
flowScope: PluginFlowScope;
|
|
37
|
+
/** The resource of a resource flow; `null` in a global flow. */
|
|
38
|
+
resourceId: number | null;
|
|
39
|
+
/** The global flow the node belongs to; `null` in a resource flow. */
|
|
40
|
+
flowId: number | null;
|
|
41
|
+
purpose?: 'editor' | 'preview';
|
|
42
|
+
}
|
|
43
|
+
export type PluginFlowFailureKind = 'transport-dispatch' | 'acknowledgement-timeout' | 'controller-rejection' | 'node-failure';
|
|
44
|
+
export type PluginFlowFailureBehavior = 'fail-flow' | 'failure-output' | 'log-and-continue';
|
|
45
|
+
export interface PluginFlowNodeValidationError {
|
|
46
|
+
field: string;
|
|
47
|
+
message: string;
|
|
48
|
+
value?: unknown;
|
|
49
|
+
}
|
|
50
|
+
/** Plain-text canvas summary with optional BCP 47 locale overrides. */
|
|
51
|
+
export interface PluginFlowNodePreviewRow {
|
|
52
|
+
label: string;
|
|
53
|
+
value: string;
|
|
54
|
+
/** Exact locale, then base language, then the default label/value are used. */
|
|
55
|
+
translations?: Record<string, {
|
|
56
|
+
label: string;
|
|
57
|
+
value: string;
|
|
58
|
+
}>;
|
|
59
|
+
}
|
|
60
|
+
/** Request-scoped storage shared while validating all nodes in a flow. */
|
|
61
|
+
export type PluginFlowNodeValidationContext = Map<string, unknown>;
|
|
62
|
+
/**
|
|
63
|
+
* Describes a single custom flow node contributed by a plugin.
|
|
64
|
+
*
|
|
65
|
+
* Node type naming convention: use "plugin.<pluginName>.<nodeName>" to
|
|
66
|
+
* guarantee no collision with core node types, e.g. "plugin.demo.send-on".
|
|
67
|
+
*/
|
|
68
|
+
interface PluginFlowNodeDefinitionBase {
|
|
69
|
+
/**
|
|
70
|
+
* Unique type string. Must be stable across plugin versions — it is stored
|
|
71
|
+
* in the database alongside saved flows. Convention: "plugin.<name>.<node>".
|
|
72
|
+
*/
|
|
73
|
+
readonly type: string;
|
|
74
|
+
/**
|
|
75
|
+
* Human-readable display name. Used in the frontend node catalog and on the
|
|
76
|
+
* canvas as a fallback when no i18n translation key is found for this type.
|
|
77
|
+
*/
|
|
78
|
+
readonly label: string;
|
|
79
|
+
/** Optional description shown in the catalog node preview. */
|
|
80
|
+
readonly description?: string;
|
|
81
|
+
/**
|
|
82
|
+
* JSON Schema object describing the node's configuration fields.
|
|
83
|
+
* The host uses this to render the config form in the frontend editor.
|
|
84
|
+
*
|
|
85
|
+
* Supports the same meta extensions as built-in schemas:
|
|
86
|
+
* { selectFromEntity: 'mqttServer', entityProperty: 'id' }
|
|
87
|
+
* { stringVariant: 'multiline' }
|
|
88
|
+
* { helpText: '...' }
|
|
89
|
+
*
|
|
90
|
+
* Canvas summaries use a top-level `preview: PluginFlowNodePreviewRow[]`
|
|
91
|
+
* (at most four plain-text rows). Include only the essential, non-secret fields.
|
|
92
|
+
* Optional `translations: { de: { label: 'Gerät', value: 'Nicht ausgewählt' } }`
|
|
93
|
+
* localizes each row; the host selects its current UI locale without another request.
|
|
94
|
+
* Default label/value strings remain required as the fallback for unsupported locales.
|
|
95
|
+
* Dynamic nodes opt in with `configSchema: { dynamic: true, properties: {}, preview: [] }`
|
|
96
|
+
* and return the summary from resolveConfigSchema for the selected configuration.
|
|
97
|
+
*/
|
|
98
|
+
readonly configSchema?: Record<string, unknown>;
|
|
99
|
+
/**
|
|
100
|
+
* Builds a configuration schema from the values selected so far. The returned
|
|
101
|
+
* schema must set `dynamic: true`; fields that should trigger a refresh set
|
|
102
|
+
* `refreshesSchema: true`.
|
|
103
|
+
* Canvas requests set `context.purpose` to `preview`: return only the preview
|
|
104
|
+
* extension and skip editor-only lookups/validation. The host refreshes visible
|
|
105
|
+
* dynamic summaries every minute so asynchronously applied changes are reflected.
|
|
106
|
+
*/
|
|
107
|
+
resolveConfigSchema?(currentConfig: Record<string, unknown>, context: PluginFlowNodeSchemaContext): Promise<Record<string, unknown>>;
|
|
108
|
+
/** Handle IDs accepted as inputs (e.g. ['input']). Empty for trigger nodes. */
|
|
109
|
+
readonly inputs: readonly string[];
|
|
110
|
+
/** Handle IDs produced as outputs (e.g. ['output']). Empty for terminal nodes. */
|
|
111
|
+
readonly outputs: readonly string[];
|
|
112
|
+
/**
|
|
113
|
+
* Whether the node is available for all resource types.
|
|
114
|
+
* Defaults to true. Set false to hide it from the catalog for all resources.
|
|
115
|
+
*/
|
|
116
|
+
readonly supportedByAllResources?: boolean;
|
|
117
|
+
/**
|
|
118
|
+
* The flow scopes this node can be used in. Defaults to `['resource']`, so a node only appears in global
|
|
119
|
+
* flows once it opts in with `['resource', 'global']` (or `['global']`).
|
|
120
|
+
*
|
|
121
|
+
* In a global flow there is no fixed resource: the `resolveConfigSchema` context
|
|
122
|
+
* (`{ flowScope, resourceId, flowId, purpose? }`) has `resourceId: null`, and a run has a triggering
|
|
123
|
+
* resource only when a resource event started it. Opt in only when the node copes with that.
|
|
124
|
+
* `supportedByAllResources` filters resource flows only.
|
|
125
|
+
*/
|
|
126
|
+
readonly flowScopes?: readonly PluginFlowScope[];
|
|
127
|
+
/**
|
|
128
|
+
* Set to true for nodes that terminate a flow branch (no further chaining
|
|
129
|
+
* expected). Controls the direction indicator in the catalog UI.
|
|
130
|
+
*/
|
|
131
|
+
readonly isOutput?: boolean;
|
|
132
|
+
/** Validates persisted configuration independently of the editor schema. */
|
|
133
|
+
validateConfig?(config: Record<string, unknown>, context: PluginFlowNodeValidationContext): Promise<PluginFlowNodeValidationError[]>;
|
|
134
|
+
/** Enables the host's shared external-effect failure policy for this node. */
|
|
135
|
+
getFailureBehavior?(config: Record<string, unknown>): PluginFlowFailureBehavior | undefined;
|
|
136
|
+
/** Classifies an execution failure for flow logs and failure outputs. */
|
|
137
|
+
getFailureKind?(error: unknown): PluginFlowFailureKind;
|
|
138
|
+
}
|
|
139
|
+
/** A plugin node that starts a flow when the plugin calls context.flows.trigger(). */
|
|
140
|
+
export interface PluginFlowTriggerNodeDefinition extends PluginFlowNodeDefinitionBase {
|
|
141
|
+
/** Marks this node as a flow trigger rather than an executable node. */
|
|
142
|
+
readonly isInput: true;
|
|
143
|
+
/** Trigger nodes do not consume a preceding node's output. */
|
|
144
|
+
readonly inputs: readonly [];
|
|
145
|
+
/** Trigger nodes always continue from the standard output handle. */
|
|
146
|
+
readonly outputs: readonly ['output'];
|
|
147
|
+
/** Trigger nodes are passthrough nodes, so the host never calls execute(). */
|
|
148
|
+
readonly execute?: never;
|
|
149
|
+
}
|
|
150
|
+
/** A plugin node executed after a flow has already started. */
|
|
151
|
+
export interface PluginFlowExecutionNodeDefinition extends PluginFlowNodeDefinitionBase {
|
|
152
|
+
readonly isInput?: false;
|
|
153
|
+
/**
|
|
154
|
+
* Execute the node. Called by the host flow engine when this node is reached
|
|
155
|
+
* during flow execution.
|
|
156
|
+
*
|
|
157
|
+
* @param node The persisted node record (id, type, data as saved config).
|
|
158
|
+
* @param input The payload object forwarded from the previous node.
|
|
159
|
+
* @param ctx Host utilities available during execution.
|
|
160
|
+
* @returns The output payload and, for multi-output nodes, the chosen handle.
|
|
161
|
+
*/
|
|
162
|
+
execute(node: {
|
|
163
|
+
id: string;
|
|
164
|
+
type: string;
|
|
165
|
+
data: Record<string, unknown>;
|
|
166
|
+
}, input: object, ctx: PluginNodeExecutionContext): Promise<{
|
|
167
|
+
payload: object;
|
|
168
|
+
outputHandle?: string;
|
|
169
|
+
}>;
|
|
170
|
+
}
|
|
171
|
+
export type PluginFlowNodeDefinition = PluginFlowTriggerNodeDefinition | PluginFlowExecutionNodeDefinition;
|
|
172
|
+
export {};
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Contract for backend plugins to register custom flow node types.
|
|
4
|
+
*
|
|
5
|
+
* Usage:
|
|
6
|
+
* export default {
|
|
7
|
+
* register(context) { ... },
|
|
8
|
+
* flowNodes: [demoOnNode, demoOffNode],
|
|
9
|
+
* } satisfies PluginBackendModule;
|
|
10
|
+
*/
|
|
11
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
12
|
+
//# sourceMappingURL=plugin-flow-node.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"plugin-flow-node.js","sourceRoot":"","sources":["../../../../../libs/plugins-backend-sdk/src/lib/plugin-flow-node.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG"}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import type { Observable } from 'rxjs';
|
|
2
|
+
import type { AuthenticatedUser } from './auth.types';
|
|
3
|
+
export interface PluginLiveSubscription {
|
|
4
|
+
/** Plugin-local topic name; the host adds the plugin namespace. */
|
|
5
|
+
topic: string;
|
|
6
|
+
identifier?: string;
|
|
7
|
+
}
|
|
8
|
+
export interface PluginLiveTopic<T extends object = object> {
|
|
9
|
+
topic: string;
|
|
10
|
+
identifier: 'none' | 'required' | 'optional';
|
|
11
|
+
/** Required. Throw to reject. Runs on every subscription set/lease renewal. */
|
|
12
|
+
authorize(subscription: PluginLiveSubscription, user: AuthenticatedUser): void | Promise<void>;
|
|
13
|
+
/** Identity always comes from the authenticated session. Release sources on unsubscribe. */
|
|
14
|
+
source(subscription: PluginLiveSubscription, user: AuthenticatedUser): Observable<{
|
|
15
|
+
data: T;
|
|
16
|
+
}>;
|
|
17
|
+
}
|
|
18
|
+
export interface PluginLiveUpdatesContext {
|
|
19
|
+
/** Register during onModuleInit. Returns an idempotent unregister function. */
|
|
20
|
+
register<T extends object>(definition: PluginLiveTopic<T>): () => void;
|
|
21
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"plugin-live-updates.js","sourceRoot":"","sources":["../../../../../libs/plugins-backend-sdk/src/lib/plugin-live-updates.ts"],"names":[],"mappings":""}
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
/** A user-facing label in every supported UI language. */
|
|
2
|
+
export interface PluginLocalizedLabel {
|
|
3
|
+
en: string;
|
|
4
|
+
de: string;
|
|
5
|
+
}
|
|
6
|
+
/**
|
|
7
|
+
* Notification category a plugin declares through
|
|
8
|
+
* {@link PluginBackendModule.notificationCategories}. The host namespaces it as
|
|
9
|
+
* `plugin.<pluginName>.<id>`, lists it in each user's notification preferences
|
|
10
|
+
* under the plugin's name and respects the user's per-channel choice (email, push,
|
|
11
|
+
* in-app toast) whenever the plugin dispatches under it.
|
|
12
|
+
*/
|
|
13
|
+
export interface PluginNotificationCategory {
|
|
14
|
+
/** Short id, unique within the plugin. Lowercase letters, digits, `-`, `_`. */
|
|
15
|
+
id: string;
|
|
16
|
+
label: PluginLocalizedLabel;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Email template a plugin declares through {@link PluginBackendModule.emailTemplates}. It works like a core
|
|
20
|
+
* template: the host stores it per installation (key `plugin.<pluginName>.<id>`), lists it in the admin email
|
|
21
|
+
* template editor under the plugin's name, renders it inside the global layout, and admins can edit subject,
|
|
22
|
+
* body and translations. The declaration only seeds it, with its shipped translations: an installed template is
|
|
23
|
+
* never overwritten ("reset to default" restores the declared version). A malformed declaration, including a
|
|
24
|
+
* Handlebars syntax error, an unknown helper or a partial, quarantines the plugin.
|
|
25
|
+
*
|
|
26
|
+
* Texts use the template translation helper, `{{t "key" "English default" name=user.username}}`; the English
|
|
27
|
+
* default is inline and `translations.de` carries the German texts (every key used must be present).
|
|
28
|
+
*/
|
|
29
|
+
export interface PluginEmailTemplate {
|
|
30
|
+
/** Short id, unique within the plugin. Lowercase letters, digits, `-`, `_`. */
|
|
31
|
+
id: string;
|
|
32
|
+
/** Name in the template list. */
|
|
33
|
+
label: PluginLocalizedLabel;
|
|
34
|
+
/** Variables the editor offers, e.g. `reservation.startTime`. `user.*`, `host.*` and `url` are always set. */
|
|
35
|
+
variables: string[];
|
|
36
|
+
/** Subject: a Handlebars string, usually one `t` call. */
|
|
37
|
+
subject: string;
|
|
38
|
+
/** Body: an MJML fragment without an `<mjml>` root (the host wraps it in the global layout). */
|
|
39
|
+
body: string;
|
|
40
|
+
/** Shipped translations per locale. `de` is required and must cover every `t` key of subject and body. */
|
|
41
|
+
translations: {
|
|
42
|
+
de: Record<string, string>;
|
|
43
|
+
} & Record<string, Record<string, string>>;
|
|
44
|
+
}
|
|
45
|
+
/** Sends one of the plugin's {@link PluginEmailTemplate}s with these variables (merged under `user`/`host`/`url`). */
|
|
46
|
+
export interface PluginNotificationEmailTemplate {
|
|
47
|
+
/** Short id of a template declared by this plugin via `emailTemplates`. */
|
|
48
|
+
template: string;
|
|
49
|
+
variables: Record<string, unknown>;
|
|
50
|
+
}
|
|
51
|
+
/** Custom email content. The host renders it inside the global email layout. */
|
|
52
|
+
export interface PluginNotificationRawEmail {
|
|
53
|
+
subject: string;
|
|
54
|
+
/** Trusted HTML fragment placed in the layout body. Takes precedence over text. */
|
|
55
|
+
html?: string;
|
|
56
|
+
/** Plain text. Used as the body (HTML-escaped) when html is omitted. */
|
|
57
|
+
text: string;
|
|
58
|
+
}
|
|
59
|
+
/** Prefer a template: admins cannot edit raw content. */
|
|
60
|
+
export type PluginNotificationEmail = PluginNotificationRawEmail | PluginNotificationEmailTemplate;
|
|
61
|
+
export interface PluginNotificationRequest {
|
|
62
|
+
/** Short id of a category declared by this plugin via `notificationCategories`. */
|
|
63
|
+
category: string;
|
|
64
|
+
/** User ids to notify. Unknown ids are skipped; duplicates are collapsed. */
|
|
65
|
+
recipients: number[];
|
|
66
|
+
title: string;
|
|
67
|
+
body: string;
|
|
68
|
+
/** In-app link target (relative to the application URL, e.g. `/resources/3`). */
|
|
69
|
+
url?: string;
|
|
70
|
+
severity?: 'info' | 'warning';
|
|
71
|
+
/** Collapses repeated push notifications that share the key. */
|
|
72
|
+
dedupeKey?: string;
|
|
73
|
+
/** When set, an email is sent to recipients whose preferences allow email for the category. A template is rendered in each recipient's language. */
|
|
74
|
+
email?: PluginNotificationEmail;
|
|
75
|
+
}
|
|
76
|
+
/** Notification dispatch for plugins. Requires the SEND_NOTIFICATIONS permission. */
|
|
77
|
+
export interface PluginNotificationsContext {
|
|
78
|
+
/**
|
|
79
|
+
* Dispatch a notification to users, honouring each user's channel preferences for the category.
|
|
80
|
+
* Rejects when the category was not declared by this plugin.
|
|
81
|
+
*/
|
|
82
|
+
dispatch(request: PluginNotificationRequest): Promise<void>;
|
|
83
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"plugin-notifications.js","sourceRoot":"","sources":["../../../../../libs/plugins-backend-sdk/src/lib/plugin-notifications.ts"],"names":[],"mappings":""}
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
/** Result of {@link PluginResourceAccessContext.canStart}. */
|
|
2
|
+
export interface PluginCanStartResult {
|
|
3
|
+
/** The user may start a session on their own right now (introduction valid, no mandatory supervision). */
|
|
4
|
+
allowed: boolean;
|
|
5
|
+
/** The user may only start a session under a supervisor (mandatory, or not introduced yet). */
|
|
6
|
+
requiresSupervision: boolean;
|
|
7
|
+
/** The resource supports supervised sessions at all (supervision allowed or required). */
|
|
8
|
+
supervisionAllowed: boolean;
|
|
9
|
+
}
|
|
10
|
+
export interface PluginMaintenanceWindow {
|
|
11
|
+
maintenanceId: number;
|
|
12
|
+
resourceId: number;
|
|
13
|
+
startTime: Date;
|
|
14
|
+
/** Null for open-ended maintenance that is still running or announced without an end. */
|
|
15
|
+
endTime: Date | null;
|
|
16
|
+
reason: string | null;
|
|
17
|
+
}
|
|
18
|
+
export interface PluginActiveSession {
|
|
19
|
+
usageId: number;
|
|
20
|
+
userId: number;
|
|
21
|
+
startTime: Date;
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* A request-bound user: the authenticated principal of an HTTP request. `request.user` of an `@Auth()`
|
|
25
|
+
* route (`AuthenticatedUser`) fits as is.
|
|
26
|
+
*/
|
|
27
|
+
export interface PluginAccessPrincipalUser {
|
|
28
|
+
id: number;
|
|
29
|
+
/**
|
|
30
|
+
* Permissions this request may use. For API-token requests core narrows them to the token's scope. When set,
|
|
31
|
+
* permission-based grants are limited to these permissions (intersected with the user's current RBAC
|
|
32
|
+
* permissions). Introducer/maintainer roles and introductions still apply, exactly as core applies them to an
|
|
33
|
+
* API-token request.
|
|
34
|
+
*/
|
|
35
|
+
effectivePermissions?: Iterable<string>;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Whom an access query is about. Pass `request.user` for request-driven checks so API-token scopes apply. A plain
|
|
39
|
+
* user id resolves the user's full RBAC permissions; use it for background work such as schedulers.
|
|
40
|
+
*/
|
|
41
|
+
export type PluginAccessPrincipal = number | PluginAccessPrincipalUser;
|
|
42
|
+
/**
|
|
43
|
+
* Read-only access and state queries over core authorization data. Requires the
|
|
44
|
+
* ACCESS_RESOURCES permission. All answers reuse the logic core uses to authorise
|
|
45
|
+
* session starts, so they never drift from what a start would actually allow.
|
|
46
|
+
*
|
|
47
|
+
* Methods that take a {@link PluginAccessPrincipal} accept either a user id or the request's user. Unknown users
|
|
48
|
+
* and unknown resources yield negative answers (`false`, all-false results, empty lists) rather than errors.
|
|
49
|
+
*/
|
|
50
|
+
export interface PluginResourceAccessContext {
|
|
51
|
+
/**
|
|
52
|
+
* Whether the user may start a session on the resource. Covers direct and group
|
|
53
|
+
* introductions, retraining blocks, introducers/maintainers and `resources.update`,
|
|
54
|
+
* plus the resource's supervision mode. It does not look at live maintenance or health
|
|
55
|
+
* state; use getMaintenanceWindows for that. Returns all-false for an unknown user or resource.
|
|
56
|
+
*/
|
|
57
|
+
canStart(principal: PluginAccessPrincipal, resourceId: number): Promise<PluginCanStartResult>;
|
|
58
|
+
/**
|
|
59
|
+
* Whether the user can manage maintenance of the resource: `resources.maintenance.manage`, or an
|
|
60
|
+
* introducer/maintainer role on the resource or one of its groups. Same check core's maintenance API uses.
|
|
61
|
+
*/
|
|
62
|
+
canMaintain(principal: PluginAccessPrincipal, resourceId: number): Promise<boolean>;
|
|
63
|
+
/**
|
|
64
|
+
* Whether the user may see WHO is using the resource: the same rule core applies to the current user's name in
|
|
65
|
+
* the resource UI and API (`full` activity access). `resources.update` and `resources.access.manage` holders,
|
|
66
|
+
* people introduced to the machine (or its introducers/maintainers) and, when the instance shows activity to
|
|
67
|
+
* everyone, every reader qualify. Machines whose activity is hidden from the user, and unknown users or
|
|
68
|
+
* resources, answer `false`. A plugin that shows a person's name next to a machine (for example who holds a
|
|
69
|
+
* reservation) should follow this answer instead of keeping its own rule. Like core's rule it does not look at
|
|
70
|
+
* hidden resource groups or account state: check that the user may see the resource at all first.
|
|
71
|
+
*/
|
|
72
|
+
canSeeUsageAttribution(principal: PluginAccessPrincipal, resourceId: number): Promise<boolean>;
|
|
73
|
+
/** Whether the user holds the RBAC permission (e.g. `resources.update`), limited to a request's scope. */
|
|
74
|
+
hasPermission(principal: PluginAccessPrincipal, permission: string): Promise<boolean>;
|
|
75
|
+
/**
|
|
76
|
+
* Ids of resources the user is introduced to in the sense of canStart's introduction rule:
|
|
77
|
+
* valid, not retraining-blocked direct or group introduction, introducer/maintainer role, or `resources.update`.
|
|
78
|
+
*/
|
|
79
|
+
listResourceIdsIntroduced(principal: PluginAccessPrincipal): Promise<number[]>;
|
|
80
|
+
/** Ids of resources whose maintenance the user can manage. */
|
|
81
|
+
listResourceIdsMaintained(principal: PluginAccessPrincipal): Promise<number[]>;
|
|
82
|
+
/**
|
|
83
|
+
* Maintenance windows overlapping [from, to). A window covers [startTime, endTime ?? infinity), so
|
|
84
|
+
* open-ended maintenance counts from its start until it is finished.
|
|
85
|
+
*/
|
|
86
|
+
getMaintenanceWindows(resourceId: number, from: Date, to: Date): Promise<PluginMaintenanceWindow[]>;
|
|
87
|
+
/** Currently running sessions on the resource, earliest first. */
|
|
88
|
+
getActiveSessions(resourceId: number): Promise<PluginActiveSession[]>;
|
|
89
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"plugin-resource-access.js","sourceRoot":"","sources":["../../../../../libs/plugins-backend-sdk/src/lib/plugin-resource-access.ts"],"names":[],"mappings":""}
|