@attraccess/plugins-backend-sdk 1.5.2 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE.md ADDED
@@ -0,0 +1,46 @@
1
+ # Prosperity Public License 3.0 – Modified Version
2
+
3
+ Copyright (c) 2025 Jan Jaap (Github: JappyJan, E-Mail: mail@janjaap.de)
4
+ Project: Attraccess
5
+
6
+ ## 1. Zweck
7
+
8
+ Diese Lizenz erlaubt die kostenlose Nutzung, Weitergabe und Änderung der Software für **nicht-kommerzielle Zwecke**. Für jede **kommerzielle Nutzung** ist eine separate Lizenz erforderlich.
9
+
10
+ Ziel ist es, Privatpersonen und gemeinnützigen Organisationen volle Freiheit zu gewähren, während Unternehmen oder gewerbliche Nutzer eine faire Lizenzierung erwerben müssen.
11
+
12
+ ## 2. Rechte und Einschränkungen
13
+
14
+ ### 2.1 Erlaubt ist:
15
+
16
+ - Nutzung, Modifikation, Verbreitung und Forks durch **Privatpersonen** oder **gemeinnützige Organisationen**,
17
+ - Nutzung für Bildung, Forschung, Hobbyprojekte oder interne, nicht-kommerzielle Zwecke.
18
+
19
+ ### 2.2 Testphase für kommerzielle Nutzung:
20
+
21
+ - Kommerzielle Nutzer (z. B. Firmen) dürfen die Software für **bis zu 30 Tage kostenlos evaluieren**.
22
+ - Nach Ablauf der Testphase ist eine kommerzielle Lizenz erforderlich.
23
+ - „Kommerzielle Nutzung“ umfasst insbesondere:
24
+ - Nutzung in oder durch Unternehmen, unabhängig von Gewinnerzielung,
25
+ - Integration in Produkte, Dienstleistungen oder Systeme mit wirtschaftlicher Zielsetzung,
26
+ - interne Verwendung in kommerziellen Prozessen oder Infrastruktur.
27
+
28
+ ## 3. Forks und abgeleitete Werke
29
+
30
+ - Forks und abgeleitete Werke **dürfen nur unter exakt denselben Lizenzbedingungen** weitergegeben werden (Prosperity Public License v3.0 – Modified).
31
+ - Forks **dürfen nicht kommerziell verwendet oder angeboten werden**, außer mit ausdrücklicher Genehmigung des ursprünglichen Autors.
32
+ - Eine **Umlizensierung** oder Verbreitung unter einer anderen Lizenz ist **nicht gestattet**.
33
+ - Dies gilt unabhängig davon, ob der Fork direkt oder indirekt auf diesem Projekt basiert.
34
+
35
+ ## 4. Teile mit anderer Lizenz (MIT)
36
+
37
+ Diese Software enthält Komponenten, die unter der MIT-Lizenz stehen. Diese Teile bleiben unter ihren ursprünglichen Bedingungen lizenziert. Siehe [LICENSE-fabinfra.md](./LICENSE-fabinfra.md).
38
+
39
+ ## 5. Keine Garantie
40
+
41
+ DIE SOFTWARE WIRD OHNE JEGLICHE GARANTIE ZUR VERFÜGUNG GESTELLT. DER AUTOR ÜBERNIMMT KEINE HAFTUNG FÜR DIREKTE ODER INDIREKTE SCHÄDEN ODER FOLGEKOSTEN.
42
+
43
+ ---
44
+
45
+ **Kommerzielle Lizenzen:**
46
+ Bitte kontaktiere [contact@attraccess.org](mailto:contact@attraccess.org) für kommerzielle Lizenzierung.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@attraccess/plugins-backend-sdk",
3
- "version": "1.5.2",
3
+ "version": "1.8.0",
4
4
  "type": "commonjs",
5
5
  "main": "./src/index.js",
6
6
  "types": "./src/index.d.ts",
@@ -23,10 +23,12 @@
23
23
  "tslib": "^2.8.1",
24
24
  "@attraccess/database-entities": "*",
25
25
  "@nestjs/common": "^11.1.0",
26
+ "@nestjs/event-emitter": "^3.1.0",
26
27
  "rxjs": "^7.8.2",
27
28
  "@nestjs/core": "^11.1.0",
29
+ "typeorm": "0.3.29",
28
30
  "@nestjs/swagger": "^11.2.0",
29
- "express": "4.21.2",
31
+ "express": "4.22.1",
30
32
  "@nestjs/passport": "^11.0.5"
31
33
  }
32
34
  }
package/src/index.d.ts CHANGED
@@ -1,4 +1,7 @@
1
1
  export * from './lib/plugin.interface';
2
+ export * from './lib/plugin-context';
3
+ export * from './lib/plugin-migrations';
4
+ export * from './lib/entity';
2
5
  export * from './lib/semver';
3
6
  export * from './lib/auth-decorator';
4
7
  export * from '@attraccess/database-entities';
package/src/index.js CHANGED
@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.entities = void 0;
4
4
  const tslib_1 = require("tslib");
5
5
  tslib_1.__exportStar(require("./lib/plugin.interface"), exports);
6
+ tslib_1.__exportStar(require("./lib/plugin-context"), exports);
7
+ tslib_1.__exportStar(require("./lib/plugin-migrations"), exports);
8
+ tslib_1.__exportStar(require("./lib/entity"), exports);
6
9
  tslib_1.__exportStar(require("./lib/semver"), exports);
7
10
  tslib_1.__exportStar(require("./lib/auth-decorator"), exports);
8
11
  tslib_1.__exportStar(require("@attraccess/database-entities"), exports);
package/src/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/plugins-backend-sdk/src/index.ts"],"names":[],"mappings":";;;;AAAA,iEAAuC;AACvC,uDAA6B;AAE7B,+DAAqC;AACrC,wEAA8C;AAC9C,kFAA0D;AAC1D,2DAAiC;AACjC,gEAAsC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/plugins-backend-sdk/src/index.ts"],"names":[],"mappings":";;;;AAAA,iEAAuC;AACvC,+DAAqC;AACrC,kEAAwC;AACxC,uDAA6B;AAC7B,uDAA6B;AAE7B,+DAAqC;AACrC,wEAA8C;AAC9C,kFAA0D;AAC1D,2DAAiC;AACjC,gEAAsC"}
@@ -0,0 +1,10 @@
1
+ export { Entity, Column, PrimaryColumn, PrimaryGeneratedColumn, Index, Unique, } from 'typeorm';
2
+ export type { Repository, EntityTarget, ObjectLiteral, FindOptionsWhere } from 'typeorm';
3
+ /**
4
+ * Constructor of a TypeORM entity a plugin ships and wants the host to register
5
+ * into the shared DataSource. A plugin lists these as a named `entities` export
6
+ * from its backend entry module; the host collects them at load time so
7
+ * {@link PluginContext.getRepository} resolves their metadata. See
8
+ * `docs/en/plugins/database-migrations.md`.
9
+ */
10
+ export type PluginEntityClass = new (...args: never[]) => object;
@@ -0,0 +1,22 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.Unique = exports.Index = exports.PrimaryGeneratedColumn = exports.PrimaryColumn = exports.Column = exports.Entity = void 0;
4
+ // Entity-definition surface re-exported from the host's single TypeORM copy,
5
+ // mirroring how plugin-migrations.ts re-exports the schema-builder helpers
6
+ // (`Table`, `TableColumn`, …). A plugin authors `@Entity` classes against the
7
+ // SDK without taking its own `typeorm` dependency: a bundled copy would be a
8
+ // different module object and break decorator-metadata/type identity at load
9
+ // time (see apps/api/src/plugin-system/plugin-loader.ts).
10
+ //
11
+ // An entity a plugin wants to query through `PluginContext.getRepository` must
12
+ // also be declared in the plugin's `entities` export so the host can register
13
+ // its metadata into the shared DataSource — schema itself stays owned by the
14
+ // plugin's migration (the host runs with `synchronize: false`).
15
+ var typeorm_1 = require("typeorm");
16
+ Object.defineProperty(exports, "Entity", { enumerable: true, get: function () { return typeorm_1.Entity; } });
17
+ Object.defineProperty(exports, "Column", { enumerable: true, get: function () { return typeorm_1.Column; } });
18
+ Object.defineProperty(exports, "PrimaryColumn", { enumerable: true, get: function () { return typeorm_1.PrimaryColumn; } });
19
+ Object.defineProperty(exports, "PrimaryGeneratedColumn", { enumerable: true, get: function () { return typeorm_1.PrimaryGeneratedColumn; } });
20
+ Object.defineProperty(exports, "Index", { enumerable: true, get: function () { return typeorm_1.Index; } });
21
+ Object.defineProperty(exports, "Unique", { enumerable: true, get: function () { return typeorm_1.Unique; } });
22
+ //# sourceMappingURL=entity.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"entity.js","sourceRoot":"","sources":["../../../../../libs/plugins-backend-sdk/src/lib/entity.ts"],"names":[],"mappings":";;;AAAA,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,6EAA6E;AAC7E,6EAA6E;AAC7E,0DAA0D;AAC1D,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,6EAA6E;AAC7E,gEAAgE;AAChE,mCAOiB;AANf,iGAAA,MAAM,OAAA;AACN,iGAAA,MAAM,OAAA;AACN,wGAAA,aAAa,OAAA;AACb,iHAAA,sBAAsB,OAAA;AACtB,gGAAA,KAAK,OAAA;AACL,iGAAA,MAAM,OAAA"}
@@ -0,0 +1,108 @@
1
+ import { DynamicModule, LoggerService, Type } from '@nestjs/common';
2
+ import { EventEmitter2 } from '@nestjs/event-emitter';
3
+ import { DataSource, EntityTarget, ObjectLiteral, Repository } from 'typeorm';
4
+ 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
+ /**
22
+ * DI token under which the host registers its MqttServerHostProvider
23
+ * implementation. The plugin context resolves the provider through this token;
24
+ * plugins never reference it directly — they call getMqttServerConfig instead.
25
+ */
26
+ export declare const MQTT_SERVER_HOST_PROVIDER: unique symbol;
27
+ /**
28
+ * Connection configuration for a single MQTT server, including its resolved
29
+ * (decrypted) credentials. A generic, broker-agnostic shape carrying only the
30
+ * fields a plugin needs to open a connection or call a server's management API.
31
+ */
32
+ export interface MqttServerConnectionConfig {
33
+ readonly id: number;
34
+ readonly name: string;
35
+ readonly host: string;
36
+ readonly port: number;
37
+ readonly useTls: boolean;
38
+ readonly username: string | null;
39
+ /** Resolved (decrypted) password. Only ever provided to permitted plugins. */
40
+ readonly password: string | null;
41
+ readonly clientId: string | null;
42
+ }
43
+ /**
44
+ * Host-side provider that resolves an MQTT server's connection config. The core
45
+ * application implements this — all credential decryption stays core-side — and
46
+ * registers it under MQTT_SERVER_HOST_PROVIDER. Plugins reach it only through
47
+ * PluginContext.getMqttServerConfig, gated by the ACCESS_MQTT_SERVERS permission.
48
+ */
49
+ export interface MqttServerHostProvider {
50
+ getServerConfig(serverId: number): Promise<MqttServerConnectionConfig | null>;
51
+ }
52
+ /**
53
+ * Curated facade handed to a backend plugin at load time. It is the single,
54
+ * versioned seam between plugin code and the host application. Adding a field is
55
+ * a minor SDK bump; removing/changing one is a major bump.
56
+ */
57
+ export interface PluginContext {
58
+ /** This plugin's own manifest (name, version, directory, id). */
59
+ readonly manifest: PluginManifestInfo;
60
+ /** Shared application event bus — the same EventEmitter2 instance the host uses. */
61
+ readonly events: EventEmitter2;
62
+ /** Shared TypeORM connection. Plugins must never re-initialise TypeOrmModule. */
63
+ readonly dataSource: DataSource;
64
+ /** Scoped logger, prefixed with the plugin name. */
65
+ readonly logger: LoggerService;
66
+ /** Typed repository accessor over the shared DataSource. */
67
+ getRepository<T extends ObjectLiteral>(entity: EntityTarget<T>): Repository<T>;
68
+ /**
69
+ * Escape hatch to resolve an arbitrary host provider by token. Privileged:
70
+ * this is where a future capability/permission gate is enforced.
71
+ */
72
+ get<T>(token: Type<T> | string | symbol): T;
73
+ /**
74
+ * Subscribe to a typed host SystemEvent. The handler is invoked with the
75
+ * event's payload whenever a domain service emits it. Requires the
76
+ * LISTEN_EVENTS permission. Returns a handle to detach the handler.
77
+ */
78
+ onEvent<E extends SystemEvent>(event: E, handler: SystemEventHandler<E>): SystemEventSubscription;
79
+ /**
80
+ * Emit a typed host SystemEvent onto the shared bus. Requires the
81
+ * EMIT_EVENTS permission. The payload is type-checked against the event.
82
+ */
83
+ emitEvent<E extends SystemEvent>(event: E, payload: SystemEventPayload[E]): void;
84
+ /**
85
+ * Resolve an MQTT server's connection configuration, including its resolved
86
+ * (decrypted) credentials. Requires the ACCESS_MQTT_SERVERS permission.
87
+ * Returns null when no server with the given id exists. The host performs all
88
+ * credential decryption; the plugin only ever receives the mapped config — it
89
+ * stays broker-agnostic (no RabbitMQ awareness).
90
+ */
91
+ getMqttServerConfig(serverId: number): Promise<MqttServerConnectionConfig | null>;
92
+ }
93
+ /**
94
+ * Shape every backend plugin's default export must satisfy. The host calls
95
+ * register(context) at load time to obtain the plugin's Nest module definition.
96
+ */
97
+ export interface PluginBackendModule {
98
+ register(context: PluginContext): DynamicModule;
99
+ /**
100
+ * Optional TypeORM entity classes this plugin owns. The host registers their
101
+ * metadata into the shared DataSource at load time so the plugin can query
102
+ * them through {@link PluginContext.getRepository}. The schema itself is owned
103
+ * by the plugin's migrations (the host runs with `synchronize: false`), so an
104
+ * entity here describes an existing table rather than creating one. Requires
105
+ * the DATABASE_ACCESS permission. See `docs/en/plugins/database-migrations.md`.
106
+ */
107
+ entities?: PluginEntityClass[];
108
+ }
@@ -0,0 +1,15 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.MQTT_SERVER_HOST_PROVIDER = exports.PLUGIN_CONTEXT = void 0;
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');
9
+ /**
10
+ * DI token under which the host registers its MqttServerHostProvider
11
+ * implementation. The plugin context resolves the provider through this token;
12
+ * plugins never reference it directly — they call getMqttServerConfig instead.
13
+ */
14
+ exports.MQTT_SERVER_HOST_PROVIDER = Symbol.for('attraccess.plugin.mqttServerHostProvider');
15
+ //# sourceMappingURL=plugin-context.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"plugin-context.js","sourceRoot":"","sources":["../../../../../libs/plugins-backend-sdk/src/lib/plugin-context.ts"],"names":[],"mappings":";;;AAMA;;;GAGG;AACU,QAAA,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;AAatE;;;;GAIG;AACU,QAAA,yBAAyB,GAAG,MAAM,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC"}
@@ -0,0 +1,16 @@
1
+ import type { MigrationInterface } from 'typeorm';
2
+ /**
3
+ * Constructor of a TypeORM migration a plugin ships. A plugin's migrations entry
4
+ * module exports one or more of these (either as named exports, mirroring the
5
+ * host's own `migrations/index.ts`, or as a default-exported array). The host
6
+ * collects them and runs them through its migration runner against a
7
+ * plugin-scoped migrations table — see {@link PluginContext} docs and
8
+ * `docs/en/plugins/database-migrations.md`.
9
+ *
10
+ * Author them exactly like host migrations: implement `up`/`down`, prefix the
11
+ * class name with a millisecond timestamp so ordering is deterministic
12
+ * (`class CreateWidgets1700000000000 implements MigrationInterface`).
13
+ */
14
+ export type PluginMigrationClass = new () => MigrationInterface;
15
+ export type { MigrationInterface, QueryRunner } from 'typeorm';
16
+ export { Table, TableColumn, TableForeignKey, TableIndex } from 'typeorm';
@@ -0,0 +1,9 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.TableIndex = exports.TableForeignKey = exports.TableColumn = exports.Table = void 0;
4
+ var typeorm_1 = require("typeorm");
5
+ Object.defineProperty(exports, "Table", { enumerable: true, get: function () { return typeorm_1.Table; } });
6
+ Object.defineProperty(exports, "TableColumn", { enumerable: true, get: function () { return typeorm_1.TableColumn; } });
7
+ Object.defineProperty(exports, "TableForeignKey", { enumerable: true, get: function () { return typeorm_1.TableForeignKey; } });
8
+ Object.defineProperty(exports, "TableIndex", { enumerable: true, get: function () { return typeorm_1.TableIndex; } });
9
+ //# sourceMappingURL=plugin-migrations.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"plugin-migrations.js","sourceRoot":"","sources":["../../../../../libs/plugins-backend-sdk/src/lib/plugin-migrations.ts"],"names":[],"mappings":";;;AAoBA,mCAA0E;AAAjE,gGAAA,KAAK,OAAA;AAAE,sGAAA,WAAW,OAAA;AAAE,0GAAA,eAAe,OAAA;AAAE,qGAAA,UAAU,OAAA"}
@@ -17,3 +17,59 @@ export type SystemEventResponse = {
17
17
  [SystemEvent.RESOURCE_USAGE_STARTED]: null;
18
18
  [SystemEvent.RESOURCE_USAGE_ENDED]: null;
19
19
  };
20
+ /**
21
+ * Typed handler a plugin registers for a given SystemEvent. It receives the
22
+ * event's payload and may return the matching response (sync or async). Thrown
23
+ * errors are isolated by the host and never propagate into the core flow.
24
+ */
25
+ export type SystemEventHandler<E extends SystemEvent> = (payload: SystemEventPayload[E]) => SystemEventResponse[E] | void | Promise<SystemEventResponse[E] | void>;
26
+ /**
27
+ * Handle returned by PluginContext.onEvent. Calling off() detaches the handler
28
+ * from the shared bus. Detaching twice is a no-op.
29
+ */
30
+ export interface SystemEventSubscription {
31
+ off(): void;
32
+ }
33
+ /**
34
+ * Discrete host capabilities a plugin may request in its manifest. A plugin can
35
+ * only use a capability whose permission it declared; the sandbox throws on any
36
+ * undeclared access. Each value gates exactly one seam of the PluginContext.
37
+ */
38
+ export declare enum PluginPermission {
39
+ /** Read the User repository via getRepository(User). */
40
+ READ_USERS = "READ_USERS",
41
+ /** Read/write the Resource repository via getRepository(Resource). */
42
+ ACCESS_RESOURCES = "ACCESS_RESOURCES",
43
+ /** Read the Setting repository via getRepository(Setting). */
44
+ READ_SETTINGS = "READ_SETTINGS",
45
+ /** Access any other repository and the raw dataSource. */
46
+ DATABASE_ACCESS = "DATABASE_ACCESS",
47
+ /** Publish events on the shared event bus (events.emit / emitAsync). */
48
+ EMIT_EVENTS = "EMIT_EVENTS",
49
+ /** Subscribe to events on the shared event bus (events.on / once / ...). */
50
+ LISTEN_EVENTS = "LISTEN_EVENTS",
51
+ /** Resolve arbitrary host providers by token via context.get(). */
52
+ RESOLVE_HOST_PROVIDERS = "RESOLVE_HOST_PROVIDERS",
53
+ /** Read an MQTT server's connection config + resolved credentials via getMqttServerConfig(). */
54
+ ACCESS_MQTT_SERVERS = "ACCESS_MQTT_SERVERS"
55
+ }
56
+ /**
57
+ * Human-readable description of each permission, surfaced to admins and plugin
58
+ * authors. Keep in sync with the PluginPermission enum.
59
+ */
60
+ export declare const PLUGIN_PERMISSION_DESCRIPTIONS: Record<PluginPermission, string>;
61
+ /**
62
+ * Returns true when the given string is a known PluginPermission value.
63
+ */
64
+ export declare function isPluginPermission(value: string): value is PluginPermission;
65
+ /**
66
+ * Thrown when a plugin accesses a host capability whose permission it did not
67
+ * declare in its manifest. The message names the plugin, the capability and the
68
+ * permission that would unlock it.
69
+ */
70
+ export declare class PluginPermissionError extends Error {
71
+ readonly pluginName: string;
72
+ readonly capability: string;
73
+ readonly requiredPermission: PluginPermission;
74
+ constructor(pluginName: string, capability: string, requiredPermission: PluginPermission);
75
+ }
@@ -1,9 +1,70 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.SystemEvent = void 0;
3
+ exports.PluginPermissionError = exports.PLUGIN_PERMISSION_DESCRIPTIONS = exports.PluginPermission = exports.SystemEvent = void 0;
4
+ exports.isPluginPermission = isPluginPermission;
4
5
  var SystemEvent;
5
6
  (function (SystemEvent) {
6
7
  SystemEvent["RESOURCE_USAGE_STARTED"] = "RESOURCE_USAGE_STARTED";
7
8
  SystemEvent["RESOURCE_USAGE_ENDED"] = "RESOURCE_USAGE_ENDED";
8
9
  })(SystemEvent || (exports.SystemEvent = SystemEvent = {}));
10
+ /**
11
+ * Discrete host capabilities a plugin may request in its manifest. A plugin can
12
+ * only use a capability whose permission it declared; the sandbox throws on any
13
+ * undeclared access. Each value gates exactly one seam of the PluginContext.
14
+ */
15
+ var PluginPermission;
16
+ (function (PluginPermission) {
17
+ /** Read the User repository via getRepository(User). */
18
+ PluginPermission["READ_USERS"] = "READ_USERS";
19
+ /** Read/write the Resource repository via getRepository(Resource). */
20
+ PluginPermission["ACCESS_RESOURCES"] = "ACCESS_RESOURCES";
21
+ /** Read the Setting repository via getRepository(Setting). */
22
+ PluginPermission["READ_SETTINGS"] = "READ_SETTINGS";
23
+ /** Access any other repository and the raw dataSource. */
24
+ PluginPermission["DATABASE_ACCESS"] = "DATABASE_ACCESS";
25
+ /** Publish events on the shared event bus (events.emit / emitAsync). */
26
+ PluginPermission["EMIT_EVENTS"] = "EMIT_EVENTS";
27
+ /** Subscribe to events on the shared event bus (events.on / once / ...). */
28
+ PluginPermission["LISTEN_EVENTS"] = "LISTEN_EVENTS";
29
+ /** Resolve arbitrary host providers by token via context.get(). */
30
+ PluginPermission["RESOLVE_HOST_PROVIDERS"] = "RESOLVE_HOST_PROVIDERS";
31
+ /** Read an MQTT server's connection config + resolved credentials via getMqttServerConfig(). */
32
+ PluginPermission["ACCESS_MQTT_SERVERS"] = "ACCESS_MQTT_SERVERS";
33
+ })(PluginPermission || (exports.PluginPermission = PluginPermission = {}));
34
+ /**
35
+ * Human-readable description of each permission, surfaced to admins and plugin
36
+ * authors. Keep in sync with the PluginPermission enum.
37
+ */
38
+ exports.PLUGIN_PERMISSION_DESCRIPTIONS = {
39
+ [PluginPermission.READ_USERS]: 'Read user accounts from the database.',
40
+ [PluginPermission.ACCESS_RESOURCES]: 'Read and write resources from the database.',
41
+ [PluginPermission.READ_SETTINGS]: 'Read application settings from the database.',
42
+ [PluginPermission.DATABASE_ACCESS]: 'Access the raw database connection and any other entity repository.',
43
+ [PluginPermission.EMIT_EVENTS]: 'Publish events on the shared application event bus.',
44
+ [PluginPermission.LISTEN_EVENTS]: 'Subscribe to events on the shared application event bus.',
45
+ [PluginPermission.RESOLVE_HOST_PROVIDERS]: 'Resolve arbitrary host services by injection token.',
46
+ [PluginPermission.ACCESS_MQTT_SERVERS]: "Read an MQTT server's connection configuration and resolved credentials.",
47
+ };
48
+ /**
49
+ * Returns true when the given string is a known PluginPermission value.
50
+ */
51
+ function isPluginPermission(value) {
52
+ return Object.prototype.hasOwnProperty.call(exports.PLUGIN_PERMISSION_DESCRIPTIONS, value);
53
+ }
54
+ /**
55
+ * Thrown when a plugin accesses a host capability whose permission it did not
56
+ * declare in its manifest. The message names the plugin, the capability and the
57
+ * permission that would unlock it.
58
+ */
59
+ class PluginPermissionError extends Error {
60
+ constructor(pluginName, capability, requiredPermission) {
61
+ super(`Plugin "${pluginName}" attempted to use "${capability}", which requires the ` +
62
+ `"${requiredPermission}" permission. Declare it in the "permissions" array of the plugin manifest.`);
63
+ this.name = 'PluginPermissionError';
64
+ this.pluginName = pluginName;
65
+ this.capability = capability;
66
+ this.requiredPermission = requiredPermission;
67
+ }
68
+ }
69
+ exports.PluginPermissionError = PluginPermissionError;
9
70
  //# sourceMappingURL=plugin.interface.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"plugin.interface.js","sourceRoot":"","sources":["../../../../../libs/plugins-backend-sdk/src/lib/plugin.interface.ts"],"names":[],"mappings":";;;AAEA,IAAY,WAGX;AAHD,WAAY,WAAW;IACrB,gEAAiD,CAAA;IACjD,4DAA6C,CAAA;AAC/C,CAAC,EAHW,WAAW,2BAAX,WAAW,QAGtB"}
1
+ {"version":3,"file":"plugin.interface.js","sourceRoot":"","sources":["../../../../../libs/plugins-backend-sdk/src/lib/plugin.interface.ts"],"names":[],"mappings":";;;AA4EA,gDAEC;AA5ED,IAAY,WAGX;AAHD,WAAY,WAAW;IACrB,gEAAiD,CAAA;IACjD,4DAA6C,CAAA;AAC/C,CAAC,EAHW,WAAW,2BAAX,WAAW,QAGtB;AA6BD;;;;GAIG;AACH,IAAY,gBAiBX;AAjBD,WAAY,gBAAgB;IAC1B,wDAAwD;IACxD,6CAAyB,CAAA;IACzB,sEAAsE;IACtE,yDAAqC,CAAA;IACrC,8DAA8D;IAC9D,mDAA+B,CAAA;IAC/B,0DAA0D;IAC1D,uDAAmC,CAAA;IACnC,wEAAwE;IACxE,+CAA2B,CAAA;IAC3B,4EAA4E;IAC5E,mDAA+B,CAAA;IAC/B,mEAAmE;IACnE,qEAAiD,CAAA;IACjD,gGAAgG;IAChG,+DAA2C,CAAA;AAC7C,CAAC,EAjBW,gBAAgB,gCAAhB,gBAAgB,QAiB3B;AAED;;;GAGG;AACU,QAAA,8BAA8B,GAAqC;IAC9E,CAAC,gBAAgB,CAAC,UAAU,CAAC,EAAE,uCAAuC;IACtE,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,EAAE,6CAA6C;IAClF,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,8CAA8C;IAChF,CAAC,gBAAgB,CAAC,eAAe,CAAC,EAAE,qEAAqE;IACzG,CAAC,gBAAgB,CAAC,WAAW,CAAC,EAAE,qDAAqD;IACrF,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,0DAA0D;IAC5F,CAAC,gBAAgB,CAAC,sBAAsB,CAAC,EAAE,qDAAqD;IAChG,CAAC,gBAAgB,CAAC,mBAAmB,CAAC,EAAE,0EAA0E;CACnH,CAAC;AAEF;;GAEG;AACH,SAAgB,kBAAkB,CAAC,KAAa;IAC9C,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,sCAA8B,EAAE,KAAK,CAAC,CAAC;AACrF,CAAC;AAED;;;;GAIG;AACH,MAAa,qBAAsB,SAAQ,KAAK;IAK9C,YAAY,UAAkB,EAAE,UAAkB,EAAE,kBAAoC;QACtF,KAAK,CACH,WAAW,UAAU,uBAAuB,UAAU,wBAAwB;YAC5E,IAAI,kBAAkB,6EAA6E,CACtG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;IAC/C,CAAC;CACF;AAfD,sDAeC"}