@attraccess/plugins-backend-sdk 1.10.0 → 1.11.0-beta.1

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.
Files changed (56) hide show
  1. package/package.json +13 -8
  2. package/src/index.d.ts +8 -0
  3. package/src/index.js +8 -0
  4. package/src/index.js.map +1 -1
  5. package/src/internal.d.ts +6 -0
  6. package/src/internal.js +11 -0
  7. package/src/internal.js.map +1 -0
  8. package/src/lib/auth.types.d.ts +3 -1
  9. package/src/lib/dual-auth.guard.js +4 -0
  10. package/src/lib/dual-auth.guard.js.map +1 -1
  11. package/src/lib/plugin-audit.d.ts +34 -33
  12. package/src/lib/plugin-audit.js +9 -9
  13. package/src/lib/plugin-audit.js.map +1 -1
  14. package/src/lib/plugin-backend-module.d.ts +71 -0
  15. package/src/lib/plugin-backend-module.js +3 -0
  16. package/src/lib/plugin-backend-module.js.map +1 -0
  17. package/src/lib/plugin-ble-fake-clock.d.ts +15 -0
  18. package/src/lib/plugin-ble-fake-clock.js +52 -0
  19. package/src/lib/plugin-ble-fake-clock.js.map +1 -0
  20. package/src/lib/plugin-ble-fake.d.ts +94 -0
  21. package/src/lib/plugin-ble-fake.js +406 -0
  22. package/src/lib/plugin-ble-fake.js.map +1 -0
  23. package/src/lib/plugin-ble-notification-stream.d.ts +28 -0
  24. package/src/lib/plugin-ble-notification-stream.js +119 -0
  25. package/src/lib/plugin-ble-notification-stream.js.map +1 -0
  26. package/src/lib/plugin-ble-session-engine.d.ts +119 -0
  27. package/src/lib/plugin-ble-session-engine.js +410 -0
  28. package/src/lib/plugin-ble-session-engine.js.map +1 -0
  29. package/src/lib/plugin-ble-validation.d.ts +71 -0
  30. package/src/lib/plugin-ble-validation.js +453 -0
  31. package/src/lib/plugin-ble-validation.js.map +1 -0
  32. package/src/lib/plugin-ble.d.ts +249 -0
  33. package/src/lib/plugin-ble.js +85 -0
  34. package/src/lib/plugin-ble.js.map +1 -0
  35. package/src/lib/plugin-context.d.ts +58 -54
  36. package/src/lib/plugin-context.js +6 -6
  37. package/src/lib/plugin-context.js.map +1 -1
  38. package/src/lib/plugin-flow-node.d.ts +52 -3
  39. package/src/lib/plugin-live-updates.d.ts +21 -0
  40. package/src/lib/plugin-live-updates.js +3 -0
  41. package/src/lib/plugin-live-updates.js.map +1 -0
  42. package/src/lib/plugin-notifications.d.ts +83 -0
  43. package/src/lib/plugin-notifications.js +3 -0
  44. package/src/lib/plugin-notifications.js.map +1 -0
  45. package/src/lib/plugin-resource-access.d.ts +89 -0
  46. package/src/lib/plugin-resource-access.js +3 -0
  47. package/src/lib/plugin-resource-access.js.map +1 -0
  48. package/src/lib/plugin.interface.d.ts +92 -5
  49. package/src/lib/plugin.interface.js +28 -1
  50. package/src/lib/plugin.interface.js.map +1 -1
  51. package/src/lib/reader-ui.d.ts +359 -0
  52. package/src/lib/reader-ui.js +115 -0
  53. package/src/lib/reader-ui.js.map +1 -0
  54. package/src/lib/shared-live-sampler.d.ts +11 -0
  55. package/src/lib/shared-live-sampler.js +33 -0
  56. package/src/lib/shared-live-sampler.js.map +1 -0
@@ -0,0 +1,249 @@
1
+ /**
2
+ * Plugin BLE transport contract (permission `BLE_TRANSPORT`).
3
+ *
4
+ * The contract is deliberately NOT a raw GATT API. A plugin registers an immutable profile (the services,
5
+ * characteristics, operations and payload bounds it may touch), binds an endpoint to a physical device through
6
+ * an administrator-approved Attractap reader, and then talks to the device through a session that only accepts
7
+ * profile keys. Core owns reader access, identity, bounds, ownership, deadlines and cleanup; the plugin owns the
8
+ * vendor semantics (advertisement parsing, credentials, command protocol).
9
+ */
10
+ /** Stable, machine-readable error codes. Never rename or remove a code. */
11
+ export declare const PluginBleErrorCode: {
12
+ readonly NOT_READY: "NOT_READY";
13
+ readonly TRANSPORT_UNAVAILABLE: "TRANSPORT_UNAVAILABLE";
14
+ readonly READER_NOT_FOUND: "READER_NOT_FOUND";
15
+ readonly READER_ACCESS_DENIED: "READER_ACCESS_DENIED";
16
+ readonly READER_OFFLINE: "READER_OFFLINE";
17
+ readonly READER_UNSUPPORTED: "READER_UNSUPPORTED";
18
+ readonly READER_BUSY: "READER_BUSY";
19
+ readonly PROFILE_NOT_REGISTERED: "PROFILE_NOT_REGISTERED";
20
+ readonly PROFILE_CONFLICT: "PROFILE_CONFLICT";
21
+ readonly INVALID_PROFILE: "INVALID_PROFILE";
22
+ readonly INVALID_ARGUMENT: "INVALID_ARGUMENT";
23
+ readonly ENDPOINT_NOT_FOUND: "ENDPOINT_NOT_FOUND";
24
+ readonly ENDPOINT_CONFLICT: "ENDPOINT_CONFLICT";
25
+ readonly ENDPOINT_BUSY: "ENDPOINT_BUSY";
26
+ readonly UNKNOWN_CHARACTERISTIC: "UNKNOWN_CHARACTERISTIC";
27
+ readonly OPERATION_NOT_ALLOWED: "OPERATION_NOT_ALLOWED";
28
+ readonly PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE";
29
+ readonly TIMEOUT: "TIMEOUT";
30
+ readonly CANCELLED: "CANCELLED";
31
+ readonly SESSION_CLOSED: "SESSION_CLOSED";
32
+ readonly DEVICE_NOT_FOUND: "DEVICE_NOT_FOUND";
33
+ readonly CONNECTION_FAILED: "CONNECTION_FAILED";
34
+ readonly DISCONNECTED: "DISCONNECTED";
35
+ readonly GATT_ERROR: "GATT_ERROR";
36
+ readonly NOTIFICATION_OVERFLOW: "NOTIFICATION_OVERFLOW";
37
+ readonly INTERNAL: "INTERNAL";
38
+ };
39
+ export type PluginBleErrorCode = (typeof PluginBleErrorCode)[keyof typeof PluginBleErrorCode];
40
+ /** Codes for which retrying the same call later can succeed without changing anything. */
41
+ export declare const PLUGIN_BLE_RETRYABLE_CODES: readonly PluginBleErrorCode[];
42
+ /**
43
+ * Error thrown (or rejected) by every BLE call. `detail` is a safe diagnostic and never contains payload bytes
44
+ * or credentials. Permission failures stay `PluginPermissionError`.
45
+ */
46
+ export declare class PluginBleError extends Error {
47
+ readonly code: PluginBleErrorCode;
48
+ readonly retryable: boolean;
49
+ readonly operation?: string;
50
+ readonly detail?: string;
51
+ constructor(code: PluginBleErrorCode, message: string, options?: {
52
+ operation?: string;
53
+ detail?: string;
54
+ });
55
+ }
56
+ /** Host caps. Values are milliseconds unless the name says otherwise. */
57
+ export declare const PLUGIN_BLE_LIMITS: {
58
+ readonly opTimeoutDefaultMs: 10000;
59
+ readonly opTimeoutMaxMs: 60000;
60
+ readonly connectTimeoutDefaultMs: 15000;
61
+ readonly connectTimeoutMaxMs: 60000;
62
+ readonly leaseDefaultMs: 30000;
63
+ readonly leaseMaxMs: number;
64
+ readonly scanDefaultMs: 5000;
65
+ readonly scanMaxMs: 15000;
66
+ readonly notificationQueueDefault: 32;
67
+ readonly notificationQueueMax: 256;
68
+ readonly payloadMaxBytes: 512;
69
+ readonly labelMaxLength: 100;
70
+ };
71
+ export declare const PLUGIN_BLE_OPERATIONS: readonly ["read", "write", "writeWithoutResponse", "notify", "indicate"];
72
+ export type PluginBleOperation = (typeof PLUGIN_BLE_OPERATIONS)[number];
73
+ export type PluginBleAddressType = 'public' | 'random';
74
+ export type PluginBleCloseReason = 'closed' | 'lease-expired' | 'cancelled' | 'disconnected' | 'reader-access-revoked' | 'endpoint-deleted' | 'shutdown' | 'error';
75
+ export interface PluginBleCharacteristicDefinition {
76
+ /** Profile-local name used by every operation. Pattern `/^[a-zA-Z][a-zA-Z0-9_-]{0,31}$/`, unique per profile. */
77
+ key: string;
78
+ /** 16-bit, 32-bit or 128-bit UUID. Normalized to lowercase 128-bit. */
79
+ uuid: string;
80
+ /** Allowed operations: non-empty, no duplicates. */
81
+ operations: PluginBleOperation[];
82
+ /** 1..512, required when `read` is allowed. */
83
+ maxReadBytes?: number;
84
+ /** 1..512, required when `write` or `writeWithoutResponse` is allowed. */
85
+ maxWriteBytes?: number;
86
+ /** 1..512, required when `notify` or `indicate` is allowed. */
87
+ maxNotificationBytes?: number;
88
+ }
89
+ export interface PluginBleServiceDefinition {
90
+ uuid: string;
91
+ characteristics: PluginBleCharacteristicDefinition[];
92
+ }
93
+ export interface PluginBleAdvertisementFilter {
94
+ serviceUuids?: string[];
95
+ /** Bluetooth company identifiers, 0..0xffff. */
96
+ manufacturerIds?: number[];
97
+ namePrefix?: string;
98
+ }
99
+ export interface PluginBleProfileDefinition {
100
+ /** Pattern `/^[a-z0-9][a-z0-9-]{0,63}$/`, unique per plugin. */
101
+ id: string;
102
+ /** Without a filter the profile cannot scan. */
103
+ advertisement?: PluginBleAdvertisementFilter;
104
+ /** At least one service with at least one characteristic. */
105
+ services: PluginBleServiceDefinition[];
106
+ limits?: {
107
+ /** Session lease cap, 1..900000 ms (default 30000). */
108
+ maxSessionMs?: number;
109
+ /** Notification queue size per subscription, 1..256 (default 32). */
110
+ maxNotificationQueue?: number;
111
+ };
112
+ }
113
+ export interface PluginBleCharacteristic {
114
+ readonly key: string;
115
+ readonly uuid: string;
116
+ readonly operations: readonly PluginBleOperation[];
117
+ readonly maxReadBytes?: number;
118
+ readonly maxWriteBytes?: number;
119
+ readonly maxNotificationBytes?: number;
120
+ }
121
+ /** Normalized, deep-frozen profile returned by `registerProfile`. */
122
+ export interface PluginBleProfile {
123
+ readonly id: string;
124
+ readonly advertisement?: {
125
+ readonly serviceUuids: readonly string[];
126
+ readonly manufacturerIds: readonly number[];
127
+ readonly namePrefix?: string;
128
+ };
129
+ readonly services: ReadonlyArray<{
130
+ readonly uuid: string;
131
+ readonly characteristics: readonly PluginBleCharacteristic[];
132
+ }>;
133
+ readonly limits: {
134
+ readonly maxSessionMs: number;
135
+ readonly maxNotificationQueue: number;
136
+ };
137
+ }
138
+ export interface PluginBleReader {
139
+ readerId: number;
140
+ name: string;
141
+ /** False when no transport driver is present or the reader cannot do BLE right now. */
142
+ available: boolean;
143
+ }
144
+ export interface PluginBleAdvertisement {
145
+ /** `XX:XX:XX:XX:XX:XX`, uppercase. */
146
+ address: string;
147
+ addressType: PluginBleAddressType;
148
+ rssi?: number;
149
+ name?: string;
150
+ /** Normalized 128-bit UUIDs. */
151
+ serviceUuids: string[];
152
+ manufacturerData: Array<{
153
+ companyId: number;
154
+ data: Uint8Array;
155
+ }>;
156
+ }
157
+ export interface PluginBleScanOptions {
158
+ /** Default 5000, max 15000. */
159
+ durationMs?: number;
160
+ signal?: AbortSignal;
161
+ }
162
+ export interface PluginBleEndpointInput {
163
+ readerId: number;
164
+ /** `XX:XX:XX:XX:XX:XX`, normalized to uppercase. */
165
+ address: string;
166
+ addressType: PluginBleAddressType;
167
+ profileId: string;
168
+ /** Max 100 characters. */
169
+ label?: string;
170
+ }
171
+ export interface PluginBleEndpointUpdate {
172
+ readerId?: number;
173
+ address?: string;
174
+ addressType?: PluginBleAddressType;
175
+ /** `null` clears the label. */
176
+ label?: string | null;
177
+ }
178
+ export interface PluginBleEndpoint {
179
+ /** Opaque stable id (UUID). */
180
+ id: string;
181
+ readerId: number;
182
+ address: string;
183
+ addressType: PluginBleAddressType;
184
+ profileId: string;
185
+ label: string | null;
186
+ createdAt: Date;
187
+ updatedAt: Date;
188
+ }
189
+ export interface PluginBleSessionOptions {
190
+ /** Aborting closes the session (or cancels the connect). */
191
+ signal?: AbortSignal;
192
+ /** Session lease, default 30000, capped by the profile's `maxSessionMs` (max 900000). */
193
+ leaseMs?: number;
194
+ /** Default 15000, max 60000. */
195
+ connectTimeoutMs?: number;
196
+ }
197
+ export interface PluginBleCallOptions {
198
+ signal?: AbortSignal;
199
+ /** Default 10000, max 60000. */
200
+ timeoutMs?: number;
201
+ }
202
+ export interface PluginBleWriteOptions extends PluginBleCallOptions {
203
+ /** Requires the `writeWithoutResponse` operation; otherwise `write` is required. */
204
+ withoutResponse?: boolean;
205
+ }
206
+ export interface PluginBleNotification {
207
+ key: string;
208
+ value: Uint8Array;
209
+ receivedAt: Date;
210
+ }
211
+ export interface PluginBleNotificationStream extends AsyncIterable<PluginBleNotification> {
212
+ /** Resolves with the next notification, in arrival order. Rejects with `TIMEOUT` or `CANCELLED` without closing the stream. */
213
+ next(options?: {
214
+ timeoutMs?: number;
215
+ signal?: AbortSignal;
216
+ }): Promise<PluginBleNotification>;
217
+ unsubscribe(): Promise<void>;
218
+ }
219
+ export interface PluginBleSession {
220
+ readonly id: string;
221
+ readonly endpointId: string;
222
+ read(key: string, options?: PluginBleCallOptions): Promise<Uint8Array>;
223
+ write(key: string, value: Uint8Array, options?: PluginBleWriteOptions): Promise<void>;
224
+ subscribe(key: string, options?: {
225
+ signal?: AbortSignal;
226
+ }): Promise<PluginBleNotificationStream>;
227
+ unsubscribe(key: string): Promise<void>;
228
+ /** Idempotent. */
229
+ close(): Promise<void>;
230
+ /** Resolves (never rejects) once the session ended, with the reason. */
231
+ readonly closed: Promise<{
232
+ reason: PluginBleCloseReason;
233
+ }>;
234
+ }
235
+ /** `context.ble`. Requires the `BLE_TRANSPORT` permission. */
236
+ export interface PluginBleContext {
237
+ /** Synchronous and valid at any time, including plugin constructors and module scope. */
238
+ registerProfile(definition: PluginBleProfileDefinition): PluginBleProfile;
239
+ listReaders(): Promise<PluginBleReader[]>;
240
+ scan(readerId: number, profileId: string, options?: PluginBleScanOptions): Promise<PluginBleAdvertisement[]>;
241
+ createEndpoint(input: PluginBleEndpointInput): Promise<PluginBleEndpoint>;
242
+ getEndpoint(id: string): Promise<PluginBleEndpoint>;
243
+ listEndpoints(): Promise<PluginBleEndpoint[]>;
244
+ updateEndpoint(id: string, update: PluginBleEndpointUpdate): Promise<PluginBleEndpoint>;
245
+ deleteEndpoint(id: string): Promise<void>;
246
+ openSession(endpointId: string, options?: PluginBleSessionOptions): Promise<PluginBleSession>;
247
+ /** Opens a session, runs `fn` and always closes the session, also when `fn` throws. */
248
+ withSession<T>(endpointId: string, fn: (session: PluginBleSession) => Promise<T>, options?: PluginBleSessionOptions): Promise<T>;
249
+ }
@@ -0,0 +1,85 @@
1
+ "use strict";
2
+ /**
3
+ * Plugin BLE transport contract (permission `BLE_TRANSPORT`).
4
+ *
5
+ * The contract is deliberately NOT a raw GATT API. A plugin registers an immutable profile (the services,
6
+ * characteristics, operations and payload bounds it may touch), binds an endpoint to a physical device through
7
+ * an administrator-approved Attractap reader, and then talks to the device through a session that only accepts
8
+ * profile keys. Core owns reader access, identity, bounds, ownership, deadlines and cleanup; the plugin owns the
9
+ * vendor semantics (advertisement parsing, credentials, command protocol).
10
+ */
11
+ Object.defineProperty(exports, "__esModule", { value: true });
12
+ exports.PLUGIN_BLE_OPERATIONS = exports.PLUGIN_BLE_LIMITS = exports.PluginBleError = exports.PLUGIN_BLE_RETRYABLE_CODES = exports.PluginBleErrorCode = void 0;
13
+ /** Stable, machine-readable error codes. Never rename or remove a code. */
14
+ exports.PluginBleErrorCode = {
15
+ NOT_READY: 'NOT_READY',
16
+ TRANSPORT_UNAVAILABLE: 'TRANSPORT_UNAVAILABLE',
17
+ READER_NOT_FOUND: 'READER_NOT_FOUND',
18
+ READER_ACCESS_DENIED: 'READER_ACCESS_DENIED',
19
+ READER_OFFLINE: 'READER_OFFLINE',
20
+ READER_UNSUPPORTED: 'READER_UNSUPPORTED',
21
+ READER_BUSY: 'READER_BUSY',
22
+ PROFILE_NOT_REGISTERED: 'PROFILE_NOT_REGISTERED',
23
+ PROFILE_CONFLICT: 'PROFILE_CONFLICT',
24
+ INVALID_PROFILE: 'INVALID_PROFILE',
25
+ INVALID_ARGUMENT: 'INVALID_ARGUMENT',
26
+ ENDPOINT_NOT_FOUND: 'ENDPOINT_NOT_FOUND',
27
+ ENDPOINT_CONFLICT: 'ENDPOINT_CONFLICT',
28
+ ENDPOINT_BUSY: 'ENDPOINT_BUSY',
29
+ UNKNOWN_CHARACTERISTIC: 'UNKNOWN_CHARACTERISTIC',
30
+ OPERATION_NOT_ALLOWED: 'OPERATION_NOT_ALLOWED',
31
+ PAYLOAD_TOO_LARGE: 'PAYLOAD_TOO_LARGE',
32
+ TIMEOUT: 'TIMEOUT',
33
+ CANCELLED: 'CANCELLED',
34
+ SESSION_CLOSED: 'SESSION_CLOSED',
35
+ DEVICE_NOT_FOUND: 'DEVICE_NOT_FOUND',
36
+ CONNECTION_FAILED: 'CONNECTION_FAILED',
37
+ DISCONNECTED: 'DISCONNECTED',
38
+ GATT_ERROR: 'GATT_ERROR',
39
+ NOTIFICATION_OVERFLOW: 'NOTIFICATION_OVERFLOW',
40
+ INTERNAL: 'INTERNAL',
41
+ };
42
+ /** Codes for which retrying the same call later can succeed without changing anything. */
43
+ exports.PLUGIN_BLE_RETRYABLE_CODES = [
44
+ exports.PluginBleErrorCode.NOT_READY,
45
+ exports.PluginBleErrorCode.TRANSPORT_UNAVAILABLE,
46
+ exports.PluginBleErrorCode.READER_OFFLINE,
47
+ exports.PluginBleErrorCode.READER_BUSY,
48
+ exports.PluginBleErrorCode.ENDPOINT_BUSY,
49
+ exports.PluginBleErrorCode.TIMEOUT,
50
+ exports.PluginBleErrorCode.DEVICE_NOT_FOUND,
51
+ exports.PluginBleErrorCode.CONNECTION_FAILED,
52
+ exports.PluginBleErrorCode.DISCONNECTED,
53
+ ];
54
+ /**
55
+ * Error thrown (or rejected) by every BLE call. `detail` is a safe diagnostic and never contains payload bytes
56
+ * or credentials. Permission failures stay `PluginPermissionError`.
57
+ */
58
+ class PluginBleError extends Error {
59
+ constructor(code, message, options = {}) {
60
+ super(message);
61
+ this.name = 'PluginBleError';
62
+ this.code = code;
63
+ this.retryable = exports.PLUGIN_BLE_RETRYABLE_CODES.includes(code);
64
+ this.operation = options.operation;
65
+ this.detail = options.detail;
66
+ }
67
+ }
68
+ exports.PluginBleError = PluginBleError;
69
+ /** Host caps. Values are milliseconds unless the name says otherwise. */
70
+ exports.PLUGIN_BLE_LIMITS = {
71
+ opTimeoutDefaultMs: 10000,
72
+ opTimeoutMaxMs: 60000,
73
+ connectTimeoutDefaultMs: 15000,
74
+ connectTimeoutMaxMs: 60000,
75
+ leaseDefaultMs: 30000,
76
+ leaseMaxMs: 15 * 60000,
77
+ scanDefaultMs: 5000,
78
+ scanMaxMs: 15000,
79
+ notificationQueueDefault: 32,
80
+ notificationQueueMax: 256,
81
+ payloadMaxBytes: 512,
82
+ labelMaxLength: 100,
83
+ };
84
+ exports.PLUGIN_BLE_OPERATIONS = ['read', 'write', 'writeWithoutResponse', 'notify', 'indicate'];
85
+ //# sourceMappingURL=plugin-ble.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"plugin-ble.js","sourceRoot":"","sources":["../../../../../libs/plugins-backend-sdk/src/lib/plugin-ble.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH,2EAA2E;AAC9D,QAAA,kBAAkB,GAAG;IAChC,SAAS,EAAE,WAAW;IACtB,qBAAqB,EAAE,uBAAuB;IAC9C,gBAAgB,EAAE,kBAAkB;IACpC,oBAAoB,EAAE,sBAAsB;IAC5C,cAAc,EAAE,gBAAgB;IAChC,kBAAkB,EAAE,oBAAoB;IACxC,WAAW,EAAE,aAAa;IAC1B,sBAAsB,EAAE,wBAAwB;IAChD,gBAAgB,EAAE,kBAAkB;IACpC,eAAe,EAAE,iBAAiB;IAClC,gBAAgB,EAAE,kBAAkB;IACpC,kBAAkB,EAAE,oBAAoB;IACxC,iBAAiB,EAAE,mBAAmB;IACtC,aAAa,EAAE,eAAe;IAC9B,sBAAsB,EAAE,wBAAwB;IAChD,qBAAqB,EAAE,uBAAuB;IAC9C,iBAAiB,EAAE,mBAAmB;IACtC,OAAO,EAAE,SAAS;IAClB,SAAS,EAAE,WAAW;IACtB,cAAc,EAAE,gBAAgB;IAChC,gBAAgB,EAAE,kBAAkB;IACpC,iBAAiB,EAAE,mBAAmB;IACtC,YAAY,EAAE,cAAc;IAC5B,UAAU,EAAE,YAAY;IACxB,qBAAqB,EAAE,uBAAuB;IAC9C,QAAQ,EAAE,UAAU;CACZ,CAAC;AAIX,0FAA0F;AAC7E,QAAA,0BAA0B,GAAkC;IACvE,0BAAkB,CAAC,SAAS;IAC5B,0BAAkB,CAAC,qBAAqB;IACxC,0BAAkB,CAAC,cAAc;IACjC,0BAAkB,CAAC,WAAW;IAC9B,0BAAkB,CAAC,aAAa;IAChC,0BAAkB,CAAC,OAAO;IAC1B,0BAAkB,CAAC,gBAAgB;IACnC,0BAAkB,CAAC,iBAAiB;IACpC,0BAAkB,CAAC,YAAY;CAChC,CAAC;AAEF;;;GAGG;AACH,MAAa,cAAe,SAAQ,KAAK;IAMvC,YAAY,IAAwB,EAAE,OAAe,EAAE,UAAmD,EAAE;QAC1G,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,kCAA0B,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC3D,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC/B,CAAC;CACF;AAdD,wCAcC;AAED,yEAAyE;AAC5D,QAAA,iBAAiB,GAAG;IAC/B,kBAAkB,EAAE,KAAM;IAC1B,cAAc,EAAE,KAAM;IACtB,uBAAuB,EAAE,KAAM;IAC/B,mBAAmB,EAAE,KAAM;IAC3B,cAAc,EAAE,KAAM;IACtB,UAAU,EAAE,EAAE,GAAG,KAAM;IACvB,aAAa,EAAE,IAAK;IACpB,SAAS,EAAE,KAAM;IACjB,wBAAwB,EAAE,EAAE;IAC5B,oBAAoB,EAAE,GAAG;IACzB,eAAe,EAAE,GAAG;IACpB,cAAc,EAAE,GAAG;CACX,CAAC;AAEE,QAAA,qBAAqB,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,sBAAsB,EAAE,QAAQ,EAAE,UAAU,CAAU,CAAC"}
@@ -1,27 +1,14 @@
1
- import { DynamicModule, LoggerService, Type } from '@nestjs/common';
2
- import type { PluginFlowNodeDefinition } from './plugin-flow-node';
1
+ import { LoggerService, Type } from '@nestjs/common';
3
2
  import { EventEmitter2 } from '@nestjs/event-emitter';
4
- import { DataSource, EntityTarget, ObjectLiteral, Repository } from 'typeorm';
5
- import { SystemEvent, SystemEventHandler, SystemEventPayload, SystemEventSubscription } from './plugin.interface';
6
- import type { PluginEntityClass } from './entity';
7
- import type { MqttCredentialProvisioningProviderFactory } from './mqtt-credential-provisioning';
3
+ import { DataSource, EntityManager, EntityTarget, ObjectLiteral, Repository } from 'typeorm';
8
4
  import type { MqttCredentialProvisioningHostProvider } from './mqtt-credential-provisioning';
9
- import type { PluginAuditContext, PluginAuditDomainDeclaration } from './plugin-audit';
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
- export declare const PLUGIN_CONTEXT: unique symbol;
15
- /**
16
- * Subset of the host manifest exposed to a plugin at runtime. The host's
17
- * LoadedPluginManifest structurally satisfies this shape.
18
- */
19
- export interface PluginManifestInfo {
20
- readonly id: string;
21
- readonly name: string;
22
- readonly version: string;
23
- readonly pluginDirectory: string;
24
- }
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';
10
+ import type { PluginBleContext } from './plugin-ble';
11
+ import { SystemEvent, SystemEventHandler, SystemEventPayload, SystemEventSubscription } from './plugin.interface';
25
12
  /**
26
13
  * DI token under which the host registers its MqttServerHostProvider
27
14
  * implementation. The plugin context resolves the provider through this token;
@@ -84,6 +71,25 @@ export interface PluginMqttClient {
84
71
  qos?: 0 | 1 | 2;
85
72
  retain?: boolean;
86
73
  }): Promise<void>;
74
+ /** Reconnect using current configured settings and restore shared topic
75
+ * registrations. Optional for compatibility with older host runtimes.
76
+ */
77
+ refreshConnection?(serverId: number): Promise<void>;
78
+ }
79
+ /**
80
+ * DI token under which a plugin's own services can inject the PluginContext.
81
+ * The host publishes the context as a module-scoped provider with this token.
82
+ */
83
+ export declare const PLUGIN_CONTEXT: unique symbol;
84
+ /**
85
+ * Subset of the host manifest exposed to a plugin at runtime. The host's
86
+ * LoadedPluginManifest structurally satisfies this shape.
87
+ */
88
+ export interface PluginManifestInfo {
89
+ readonly id: string;
90
+ readonly name: string;
91
+ readonly version: string;
92
+ readonly pluginDirectory: string;
87
93
  }
88
94
  /** Host flow functionality available to plugins with the TRIGGER_FLOWS permission. */
89
95
  export interface PluginFlowsContext {
@@ -104,8 +110,22 @@ export interface PluginSecretsContext {
104
110
  * a minor SDK bump; removing/changing one is a major bump.
105
111
  */
106
112
  export interface PluginContext {
113
+ /**
114
+ * Version of the running Attraccess host (the one plugin compatibility is checked against). Optional for hosts
115
+ * predating this field, so a plugin that needs it must handle its absence.
116
+ */
117
+ readonly hostVersion?: string;
118
+ /** Shared authenticated UI transport. Optional for hosts predating this capability. */
119
+ readonly liveUpdates?: PluginLiveUpdatesContext;
107
120
  /** Optional for compatibility with hosts predating generic plugin audit support. */
108
121
  readonly audit?: PluginAuditContext;
122
+ /** Reader UI helpers. Guarded getter: throws PluginPermissionError without READER_UI. */
123
+ readonly readerUi?: PluginReaderUiApi;
124
+ /**
125
+ * BLE transport through administrator-approved Attractap readers. Guarded getter: throws PluginPermissionError
126
+ * without BLE_TRANSPORT. Optional so plugins still type-check against hosts predating it.
127
+ */
128
+ readonly ble?: PluginBleContext;
109
129
  /** This plugin's own manifest (name, version, directory, id). */
110
130
  readonly manifest: PluginManifestInfo;
111
131
  /** Shared application event bus — the same EventEmitter2 instance the host uses. */
@@ -148,39 +168,23 @@ export interface PluginContext {
148
168
  readonly flows: PluginFlowsContext;
149
169
  /** Encrypt and decrypt this plugin's secret material. Requires MANAGE_SECRETS. */
150
170
  readonly secrets: PluginSecretsContext;
151
- }
152
- /**
153
- * Shape every backend plugin's default export must satisfy. The host calls
154
- * register(context) at load time to obtain the plugin's Nest module definition.
155
- */
156
- export interface PluginBackendModule {
157
- register(context: PluginContext): DynamicModule;
158
- /**
159
- * Optional TypeORM entity classes this plugin owns. The host registers their
160
- * metadata into the shared DataSource at load time so the plugin can query
161
- * them through {@link PluginContext.getRepository}. The schema itself is owned
162
- * by the plugin's migrations (the host runs with `synchronize: false`), so an
163
- * entity here describes an existing table rather than creating one. Requires
164
- * the DATABASE_ACCESS permission. See `docs/en/plugins/database-migrations.md`.
165
- */
166
- entities?: PluginEntityClass[];
171
+ /** Notify users under plugin-declared categories. Requires SEND_NOTIFICATIONS. */
172
+ readonly notifications: PluginNotificationsContext;
173
+ /** Tells the host UI that this plugin's `startBlockedQuery` answer changed. Requires ACCESS_HOOKS. */
174
+ readonly startBlocked: PluginStartBlockedApi;
175
+ /** Read-only authorization, maintenance and session queries. Requires ACCESS_RESOURCES. */
176
+ readonly resourceAccess: PluginResourceAccessContext;
167
177
  /**
168
- * Optional custom flow node types this plugin contributes. The host registers
169
- * them into the flow engine so they appear in the frontend node catalog and
170
- * can be executed like built-in node types. No extra permission is required.
178
+ * Run `fn` in a serialized database transaction. Concurrent callers (core lifecycle writes included)
179
+ * run one at a time on SQLite, so check-then-write sequences such as overlap checks are race-free.
180
+ * The transaction commits when `fn` resolves and rolls back when it throws. Requires DATABASE_ACCESS.
171
181
  *
172
- * Type naming convention: "plugin.<pluginName>.<nodeName>".
173
- */
174
- flowNodes?: PluginFlowNodeDefinition[] | ((context: PluginContext) => PluginFlowNodeDefinition[]);
175
- /**
176
- * Optional audit domains this plugin contributes. The host registers the
177
- * declarations at load time and enforces them on every event the plugin
178
- * records through {@link PluginContext.audit}: only declared actions, subject
179
- * types and detail fields are accepted, and events are stored under the
180
- * declared domain. Domains must not collide with host domains or with other
181
- * plugins. No extra permission is required.
182
+ * The queue is shared with every core session start and end, so keep `fn` short and limited to database
183
+ * work through the given manager: no HTTP, MQTT, email or other I/O inside. Do not nest calls: a
184
+ * runSerialized started inside `fn` would wait for `fn` itself, so the host rejects it with an error;
185
+ * pass the manager down instead. Core services that write through the same queue (session start/end)
186
+ * must not be awaited inside `fn` either.
182
187
  */
183
- auditDomains?: PluginAuditDomainDeclaration[] | ((context: PluginContext) => PluginAuditDomainDeclaration[]);
184
- /** Optional broker credential provider offered to other integrations by this plugin. */
185
- credentialProvisioningProvider?: MqttCredentialProvisioningProviderFactory;
188
+ runSerialized<T>(fn: (manager: EntityManager) => Promise<T>): Promise<T>;
186
189
  }
190
+ export { PluginBackendModule } from './plugin-backend-module';
@@ -1,15 +1,15 @@
1
1
  "use strict";
2
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');
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":";;;AAUA;;;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"}
1
+ {"version":3,"file":"plugin-context.js","sourceRoot":"","sources":["../../../../../libs/plugins-backend-sdk/src/lib/plugin-context.ts"],"names":[],"mappings":";;;AAWA;;;;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"}
@@ -19,6 +19,26 @@ export interface PluginNodeExecutionContext {
19
19
  * ({{resource.id}}, {{payload.*}}, etc.).
20
20
  */
21
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';
22
42
  }
23
43
  export type PluginFlowFailureKind = 'transport-dispatch' | 'acknowledgement-timeout' | 'controller-rejection' | 'node-failure';
24
44
  export type PluginFlowFailureBehavior = 'fail-flow' | 'failure-output' | 'log-and-continue';
@@ -27,6 +47,16 @@ export interface PluginFlowNodeValidationError {
27
47
  message: string;
28
48
  value?: unknown;
29
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
+ }
30
60
  /** Request-scoped storage shared while validating all nodes in a flow. */
31
61
  export type PluginFlowNodeValidationContext = Map<string, unknown>;
32
62
  /**
@@ -56,16 +86,25 @@ interface PluginFlowNodeDefinitionBase {
56
86
  * { selectFromEntity: 'mqttServer', entityProperty: 'id' }
57
87
  * { stringVariant: 'multiline' }
58
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.
59
97
  */
60
98
  readonly configSchema?: Record<string, unknown>;
61
99
  /**
62
100
  * Builds a configuration schema from the values selected so far. The returned
63
101
  * schema must set `dynamic: true`; fields that should trigger a refresh set
64
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.
65
106
  */
66
- resolveConfigSchema?(currentConfig: Record<string, unknown>, context: {
67
- resourceId: number;
68
- }): Promise<Record<string, unknown>>;
107
+ resolveConfigSchema?(currentConfig: Record<string, unknown>, context: PluginFlowNodeSchemaContext): Promise<Record<string, unknown>>;
69
108
  /** Handle IDs accepted as inputs (e.g. ['input']). Empty for trigger nodes. */
70
109
  readonly inputs: readonly string[];
71
110
  /** Handle IDs produced as outputs (e.g. ['output']). Empty for terminal nodes. */
@@ -75,6 +114,16 @@ interface PluginFlowNodeDefinitionBase {
75
114
  * Defaults to true. Set false to hide it from the catalog for all resources.
76
115
  */
77
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[];
78
127
  /**
79
128
  * Set to true for nodes that terminate a flow branch (no further chaining
80
129
  * expected). Controls the direction indicator in the catalog UI.
@@ -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,3 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ //# sourceMappingURL=plugin-live-updates.js.map
@@ -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":""}