@attraccess/plugins-backend-sdk 1.11.0-beta.0 → 1.11.0-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/package.json +8 -8
  2. package/src/index.d.ts +4 -0
  3. package/src/index.js +4 -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-decorator.d.ts +4 -3
  9. package/src/lib/auth-decorator.js.map +1 -1
  10. package/src/lib/auth.types.d.ts +5 -1
  11. package/src/lib/dual-auth.guard.js +4 -0
  12. package/src/lib/dual-auth.guard.js.map +1 -1
  13. package/src/lib/plugin-audit.d.ts +16 -2
  14. package/src/lib/plugin-audit.js +8 -3
  15. package/src/lib/plugin-audit.js.map +1 -1
  16. package/src/lib/plugin-backend-module.d.ts +15 -1
  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 +102 -0
  21. package/src/lib/plugin-ble-fake.js +424 -0
  22. package/src/lib/plugin-ble-fake.js.map +1 -0
  23. package/src/lib/plugin-ble-notification-stream.d.ts +30 -0
  24. package/src/lib/plugin-ble-notification-stream.js +123 -0
  25. package/src/lib/plugin-ble-notification-stream.js.map +1 -0
  26. package/src/lib/plugin-ble-session-engine.d.ts +151 -0
  27. package/src/lib/plugin-ble-session-engine.js +465 -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 +258 -0
  33. package/src/lib/plugin-ble.js +88 -0
  34. package/src/lib/plugin-ble.js.map +1 -0
  35. package/src/lib/plugin-context.d.ts +6 -0
  36. package/src/lib/plugin-context.js.map +1 -1
  37. package/src/lib/plugin-permissions.d.ts +65 -0
  38. package/src/lib/plugin-permissions.js +107 -0
  39. package/src/lib/plugin-permissions.js.map +1 -0
  40. package/src/lib/plugin-resource-access.d.ts +2 -1
  41. package/src/lib/plugin.interface.d.ts +20 -2
  42. package/src/lib/plugin.interface.js +8 -0
  43. package/src/lib/plugin.interface.js.map +1 -1
  44. package/src/lib/reader-ui.d.ts +42 -0
  45. package/src/lib/reader-ui.js.map +1 -1
@@ -0,0 +1,258 @@
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
+ /** Smallest ATT MTU (BLE core spec); a link that reports none counts as this. */
71
+ readonly mtuMin: 23;
72
+ readonly mtuMax: 517;
73
+ };
74
+ export declare const PLUGIN_BLE_OPERATIONS: readonly ["read", "write", "writeWithoutResponse", "notify", "indicate"];
75
+ export type PluginBleOperation = (typeof PLUGIN_BLE_OPERATIONS)[number];
76
+ export type PluginBleAddressType = 'public' | 'random';
77
+ export type PluginBleCloseReason = 'closed' | 'lease-expired' | 'cancelled' | 'disconnected' | 'reader-access-revoked' | 'endpoint-deleted' | 'shutdown' | 'error';
78
+ export interface PluginBleCharacteristicDefinition {
79
+ /** Profile-local name used by every operation. Pattern `/^[a-zA-Z][a-zA-Z0-9_-]{0,31}$/`, unique per profile. */
80
+ key: string;
81
+ /** 16-bit, 32-bit or 128-bit UUID. Normalized to lowercase 128-bit. */
82
+ uuid: string;
83
+ /** Allowed operations: non-empty, no duplicates. */
84
+ operations: PluginBleOperation[];
85
+ /** 1..512, required when `read` is allowed. */
86
+ maxReadBytes?: number;
87
+ /** 1..512, required when `write` or `writeWithoutResponse` is allowed. */
88
+ maxWriteBytes?: number;
89
+ /** 1..512, required when `notify` or `indicate` is allowed. */
90
+ maxNotificationBytes?: number;
91
+ }
92
+ export interface PluginBleServiceDefinition {
93
+ uuid: string;
94
+ characteristics: PluginBleCharacteristicDefinition[];
95
+ }
96
+ export interface PluginBleAdvertisementFilter {
97
+ serviceUuids?: string[];
98
+ /** Bluetooth company identifiers, 0..0xffff. */
99
+ manufacturerIds?: number[];
100
+ namePrefix?: string;
101
+ }
102
+ export interface PluginBleProfileDefinition {
103
+ /** Pattern `/^[a-z0-9][a-z0-9-]{0,63}$/`, unique per plugin. */
104
+ id: string;
105
+ /** Without a filter the profile cannot scan. */
106
+ advertisement?: PluginBleAdvertisementFilter;
107
+ /** At least one service with at least one characteristic. */
108
+ services: PluginBleServiceDefinition[];
109
+ limits?: {
110
+ /** Session lease cap, 1..900000 ms (default 30000). */
111
+ maxSessionMs?: number;
112
+ /** Notification queue size per subscription, 1..256 (default 32). */
113
+ maxNotificationQueue?: number;
114
+ };
115
+ }
116
+ export interface PluginBleCharacteristic {
117
+ readonly key: string;
118
+ readonly uuid: string;
119
+ readonly operations: readonly PluginBleOperation[];
120
+ readonly maxReadBytes?: number;
121
+ readonly maxWriteBytes?: number;
122
+ readonly maxNotificationBytes?: number;
123
+ }
124
+ /** Normalized, deep-frozen profile returned by `registerProfile`. */
125
+ export interface PluginBleProfile {
126
+ readonly id: string;
127
+ readonly advertisement?: {
128
+ readonly serviceUuids: readonly string[];
129
+ readonly manufacturerIds: readonly number[];
130
+ readonly namePrefix?: string;
131
+ };
132
+ readonly services: ReadonlyArray<{
133
+ readonly uuid: string;
134
+ readonly characteristics: readonly PluginBleCharacteristic[];
135
+ }>;
136
+ readonly limits: {
137
+ readonly maxSessionMs: number;
138
+ readonly maxNotificationQueue: number;
139
+ };
140
+ }
141
+ export interface PluginBleReader {
142
+ readerId: number;
143
+ name: string;
144
+ /** False when no transport driver is present or the reader cannot do BLE right now. */
145
+ available: boolean;
146
+ }
147
+ export interface PluginBleAdvertisement {
148
+ /** `XX:XX:XX:XX:XX:XX`, uppercase. */
149
+ address: string;
150
+ addressType: PluginBleAddressType;
151
+ rssi?: number;
152
+ name?: string;
153
+ /** Normalized 128-bit UUIDs. */
154
+ serviceUuids: string[];
155
+ manufacturerData: Array<{
156
+ companyId: number;
157
+ data: Uint8Array;
158
+ }>;
159
+ }
160
+ export interface PluginBleScanOptions {
161
+ /** Default 5000, max 15000. */
162
+ durationMs?: number;
163
+ signal?: AbortSignal;
164
+ }
165
+ export interface PluginBleEndpointInput {
166
+ readerId: number;
167
+ /** `XX:XX:XX:XX:XX:XX`, normalized to uppercase. */
168
+ address: string;
169
+ addressType: PluginBleAddressType;
170
+ profileId: string;
171
+ /** Max 100 characters. */
172
+ label?: string;
173
+ }
174
+ export interface PluginBleEndpointUpdate {
175
+ readerId?: number;
176
+ address?: string;
177
+ addressType?: PluginBleAddressType;
178
+ /** `null` clears the label. */
179
+ label?: string | null;
180
+ }
181
+ export interface PluginBleEndpoint {
182
+ /** Opaque stable id (UUID). */
183
+ id: string;
184
+ readerId: number;
185
+ address: string;
186
+ addressType: PluginBleAddressType;
187
+ profileId: string;
188
+ label: string | null;
189
+ createdAt: Date;
190
+ updatedAt: Date;
191
+ }
192
+ export interface PluginBleSessionOptions {
193
+ /** Aborting closes the session (or cancels the connect). */
194
+ signal?: AbortSignal;
195
+ /** Session lease, default 30000, capped by the profile's `maxSessionMs` (max 900000). */
196
+ leaseMs?: number;
197
+ /** Default 15000, max 60000. */
198
+ connectTimeoutMs?: number;
199
+ }
200
+ export interface PluginBleCallOptions {
201
+ signal?: AbortSignal;
202
+ /** Default 10000, max 60000. */
203
+ timeoutMs?: number;
204
+ }
205
+ export interface PluginBleWriteOptions extends PluginBleCallOptions {
206
+ /** Requires the `writeWithoutResponse` operation; otherwise `write` is required. */
207
+ withoutResponse?: boolean;
208
+ }
209
+ export interface PluginBleNotification {
210
+ key: string;
211
+ value: Uint8Array;
212
+ receivedAt: Date;
213
+ }
214
+ export interface PluginBleNotificationStream extends AsyncIterable<PluginBleNotification> {
215
+ /** Resolves with the next notification, in arrival order. Rejects with `TIMEOUT` or `CANCELLED` without closing the stream. */
216
+ next(options?: {
217
+ timeoutMs?: number;
218
+ signal?: AbortSignal;
219
+ }): Promise<PluginBleNotification>;
220
+ unsubscribe(): Promise<void>;
221
+ }
222
+ export interface PluginBleSession {
223
+ readonly id: string;
224
+ readonly endpointId: string;
225
+ /**
226
+ * Negotiated ATT MTU of the connection (23..517). A write without response carries at most `mtu - 3` bytes;
227
+ * larger ones reject with `PAYLOAD_TOO_LARGE` (detail `exceeds-mtu`). Writes with response may use the long-write
228
+ * procedure up to the profile bound.
229
+ */
230
+ readonly mtu: number;
231
+ read(key: string, options?: PluginBleCallOptions): Promise<Uint8Array>;
232
+ write(key: string, value: Uint8Array, options?: PluginBleWriteOptions): Promise<void>;
233
+ subscribe(key: string, options?: {
234
+ signal?: AbortSignal;
235
+ }): Promise<PluginBleNotificationStream>;
236
+ unsubscribe(key: string): Promise<void>;
237
+ /** Idempotent. */
238
+ close(): Promise<void>;
239
+ /** Resolves (never rejects) once the session ended, with the reason. */
240
+ readonly closed: Promise<{
241
+ reason: PluginBleCloseReason;
242
+ }>;
243
+ }
244
+ /** `context.ble`. Requires the `BLE_TRANSPORT` permission. */
245
+ export interface PluginBleContext {
246
+ /** Synchronous and valid at any time, including plugin constructors and module scope. */
247
+ registerProfile(definition: PluginBleProfileDefinition): PluginBleProfile;
248
+ listReaders(): Promise<PluginBleReader[]>;
249
+ scan(readerId: number, profileId: string, options?: PluginBleScanOptions): Promise<PluginBleAdvertisement[]>;
250
+ createEndpoint(input: PluginBleEndpointInput): Promise<PluginBleEndpoint>;
251
+ getEndpoint(id: string): Promise<PluginBleEndpoint>;
252
+ listEndpoints(): Promise<PluginBleEndpoint[]>;
253
+ updateEndpoint(id: string, update: PluginBleEndpointUpdate): Promise<PluginBleEndpoint>;
254
+ deleteEndpoint(id: string): Promise<void>;
255
+ openSession(endpointId: string, options?: PluginBleSessionOptions): Promise<PluginBleSession>;
256
+ /** Opens a session, runs `fn` and always closes the session, also when `fn` throws. */
257
+ withSession<T>(endpointId: string, fn: (session: PluginBleSession) => Promise<T>, options?: PluginBleSessionOptions): Promise<T>;
258
+ }
@@ -0,0 +1,88 @@
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
+ /** Smallest ATT MTU (BLE core spec); a link that reports none counts as this. */
84
+ mtuMin: 23,
85
+ mtuMax: 517,
86
+ };
87
+ exports.PLUGIN_BLE_OPERATIONS = ['read', 'write', 'writeWithoutResponse', 'notify', 'indicate'];
88
+ //# 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;IACnB,iFAAiF;IACjF,MAAM,EAAE,EAAE;IACV,MAAM,EAAE,GAAG;CACH,CAAC;AAEE,QAAA,qBAAqB,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,sBAAsB,EAAE,QAAQ,EAAE,UAAU,CAAU,CAAC"}
@@ -7,6 +7,7 @@ import type { PluginReaderUiApi, PluginStartBlockedApi } from './reader-ui';
7
7
  import type { PluginNotificationsContext } from './plugin-notifications';
8
8
  import type { PluginResourceAccessContext } from './plugin-resource-access';
9
9
  import type { PluginLiveUpdatesContext } from './plugin-live-updates';
10
+ import type { PluginBleContext } from './plugin-ble';
10
11
  import { SystemEvent, SystemEventHandler, SystemEventPayload, SystemEventSubscription } from './plugin.interface';
11
12
  /**
12
13
  * DI token under which the host registers its MqttServerHostProvider
@@ -120,6 +121,11 @@ export interface PluginContext {
120
121
  readonly audit?: PluginAuditContext;
121
122
  /** Reader UI helpers. Guarded getter: throws PluginPermissionError without READER_UI. */
122
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;
123
129
  /** This plugin's own manifest (name, version, directory, id). */
124
130
  readonly manifest: PluginManifestInfo;
125
131
  /** Shared application event bus — the same EventEmitter2 instance the host uses. */
@@ -1 +1 @@
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"}
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"}
@@ -0,0 +1,65 @@
1
+ import type { SystemPermission } from '@attraccess/shared';
2
+ import type { PluginLocalizedLabel } from './plugin-notifications';
3
+ /**
4
+ * RBAC permission keys a plugin declares through `PluginBackendModule.permissions`. The host registers them in the
5
+ * permission catalog at load time, so they appear in the role editor and the API-token picker, and the plugin
6
+ * guards its routes with them like core keys (`@Auth(PERMISSIONS.keys['acme.widgets.read'])`).
7
+ *
8
+ * Not to be confused with the manifest `permissions` field, which lists host capabilities ({@link PluginPermission}).
9
+ */
10
+ /** Lowercase dotted segments, at least two, for example `acme.widgets.read`. */
11
+ export declare const PLUGIN_PERMISSION_KEY_PATTERN: RegExp;
12
+ export declare const PLUGIN_PERMISSION_KEY_MAX_LENGTH = 100;
13
+ /** Namespaces of the core catalog. A plugin key must not start with one of them. */
14
+ export declare const RESERVED_PERMISSION_NAMESPACES: readonly ["resources.", "users.", "system.", "billing."];
15
+ /** The system roles a plugin may grant its keys to on first registration. */
16
+ export declare const PLUGIN_PERMISSION_DEFAULT_ROLES: readonly ["user", "resource-manager", "user-manager", "billing-manager", "system-admin", "administrator"];
17
+ export type PluginPermissionDefaultRole = (typeof PLUGIN_PERMISSION_DEFAULT_ROLES)[number];
18
+ export declare const PLUGIN_PERMISSION_LIMITS: {
19
+ readonly permissionsPerPlugin: 64;
20
+ readonly labelLength: 120;
21
+ readonly descriptionLength: 500;
22
+ };
23
+ declare const pluginPermissionKeyBrand: unique symbol;
24
+ /** A key returned by {@link definePluginPermissions}. Only declared keys carry the brand. */
25
+ export type PluginPermissionKey<K extends string = string> = K & {
26
+ readonly [pluginPermissionKeyBrand]: true;
27
+ };
28
+ /** What `@Auth`, `@AuthAny`, `@SessionAuth` and `resourceAccess.hasPermission` accept. */
29
+ export type PermissionKey = SystemPermission | PluginPermissionKey;
30
+ export interface PluginPermissionDefinition<K extends string = string> {
31
+ readonly key: K;
32
+ readonly label: PluginLocalizedLabel;
33
+ readonly description: PluginLocalizedLabel;
34
+ /**
35
+ * System roles that receive the key when the host registers it for the first time. Later boots never grant it
36
+ * again, so an administrator's removal sticks. `administrator` always holds every plugin key, listed or not.
37
+ */
38
+ readonly defaultRoles?: readonly PluginPermissionDefaultRole[];
39
+ }
40
+ export interface PluginPermissionsDeclaration {
41
+ /** Group label in the role editor. Defaults to the plugin name from the manifest. */
42
+ readonly category?: PluginLocalizedLabel;
43
+ readonly permissions: readonly PluginPermissionDefinition[];
44
+ }
45
+ export type DefinedPluginPermissions<P extends readonly PluginPermissionDefinition[]> = PluginPermissionsDeclaration & {
46
+ readonly permissions: P;
47
+ /** The declared keys, typed for `@Auth` and friends. */
48
+ readonly keys: {
49
+ readonly [D in P[number] as D['key']]: PluginPermissionKey<D['key']>;
50
+ };
51
+ };
52
+ /** Declares a plugin's permission keys and returns them typed for the auth decorators. */
53
+ export declare function definePluginPermissions<const P extends readonly PluginPermissionDefinition[]>(declaration: {
54
+ category?: PluginLocalizedLabel;
55
+ permissions: P;
56
+ }): DefinedPluginPermissions<P>;
57
+ /** Why `key` cannot be a plugin permission key, or null when its shape is valid. */
58
+ export declare function pluginPermissionKeyError(key: unknown): string | null;
59
+ /**
60
+ * Validates a plugin's permission declaration and returns it unchanged. Throws a descriptive error on any
61
+ * violation; the host quarantines the plugin in that case. Collisions with core keys and with keys of other
62
+ * plugins are checked by the host.
63
+ */
64
+ export declare function validatePluginPermissionsDeclaration(declaration: unknown): PluginPermissionsDeclaration;
65
+ export {};
@@ -0,0 +1,107 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.PLUGIN_PERMISSION_LIMITS = exports.PLUGIN_PERMISSION_DEFAULT_ROLES = exports.RESERVED_PERMISSION_NAMESPACES = exports.PLUGIN_PERMISSION_KEY_MAX_LENGTH = exports.PLUGIN_PERMISSION_KEY_PATTERN = void 0;
4
+ exports.definePluginPermissions = definePluginPermissions;
5
+ exports.pluginPermissionKeyError = pluginPermissionKeyError;
6
+ exports.validatePluginPermissionsDeclaration = validatePluginPermissionsDeclaration;
7
+ /**
8
+ * RBAC permission keys a plugin declares through `PluginBackendModule.permissions`. The host registers them in the
9
+ * permission catalog at load time, so they appear in the role editor and the API-token picker, and the plugin
10
+ * guards its routes with them like core keys (`@Auth(PERMISSIONS.keys['acme.widgets.read'])`).
11
+ *
12
+ * Not to be confused with the manifest `permissions` field, which lists host capabilities ({@link PluginPermission}).
13
+ */
14
+ /** Lowercase dotted segments, at least two, for example `acme.widgets.read`. */
15
+ exports.PLUGIN_PERMISSION_KEY_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
16
+ exports.PLUGIN_PERMISSION_KEY_MAX_LENGTH = 100;
17
+ /** Namespaces of the core catalog. A plugin key must not start with one of them. */
18
+ exports.RESERVED_PERMISSION_NAMESPACES = ['resources.', 'users.', 'system.', 'billing.'];
19
+ /** The system roles a plugin may grant its keys to on first registration. */
20
+ exports.PLUGIN_PERMISSION_DEFAULT_ROLES = [
21
+ 'user',
22
+ 'resource-manager',
23
+ 'user-manager',
24
+ 'billing-manager',
25
+ 'system-admin',
26
+ 'administrator',
27
+ ];
28
+ exports.PLUGIN_PERMISSION_LIMITS = {
29
+ permissionsPerPlugin: 64,
30
+ labelLength: 120,
31
+ descriptionLength: 500,
32
+ };
33
+ /** Declares a plugin's permission keys and returns them typed for the auth decorators. */
34
+ function definePluginPermissions(declaration) {
35
+ const keys = Object.fromEntries(declaration.permissions.map((permission) => [permission.key, permission.key]));
36
+ return Object.freeze(Object.assign(Object.assign({}, declaration), { keys: Object.freeze(keys) }));
37
+ }
38
+ // Realm-agnostic: plugin code may build its declaration in another realm, whose Object.prototype differs.
39
+ const isPlainRecord = (value) => {
40
+ if (!value || typeof value !== 'object' || Array.isArray(value))
41
+ return false;
42
+ const prototype = Object.getPrototypeOf(value);
43
+ return prototype === null || Object.getPrototypeOf(prototype) === null;
44
+ };
45
+ function validateLocalized(where, value, maxLength) {
46
+ if (!isPlainRecord(value))
47
+ throw new Error(`${where} must be an object with "en" and "de"`);
48
+ for (const locale of ['en', 'de']) {
49
+ const text = value[locale];
50
+ if (typeof text !== 'string' || text.trim().length === 0 || text.length > maxLength)
51
+ throw new Error(`${where}.${locale} must be 1-${maxLength} characters`);
52
+ }
53
+ }
54
+ /** Why `key` cannot be a plugin permission key, or null when its shape is valid. */
55
+ function pluginPermissionKeyError(key) {
56
+ if (typeof key !== 'string' ||
57
+ key.length > exports.PLUGIN_PERMISSION_KEY_MAX_LENGTH ||
58
+ !exports.PLUGIN_PERMISSION_KEY_PATTERN.test(key))
59
+ return `must match ${exports.PLUGIN_PERMISSION_KEY_PATTERN.source} and be at most ${exports.PLUGIN_PERMISSION_KEY_MAX_LENGTH} characters`;
60
+ const reserved = exports.RESERVED_PERMISSION_NAMESPACES.find((namespace) => key.startsWith(namespace));
61
+ if (reserved)
62
+ return `must not use the reserved core namespace "${reserved}"`;
63
+ return null;
64
+ }
65
+ /**
66
+ * Validates a plugin's permission declaration and returns it unchanged. Throws a descriptive error on any
67
+ * violation; the host quarantines the plugin in that case. Collisions with core keys and with keys of other
68
+ * plugins are checked by the host.
69
+ */
70
+ function validatePluginPermissionsDeclaration(declaration) {
71
+ if (!isPlainRecord(declaration))
72
+ throw new Error('Plugin permissions must be a plain object');
73
+ if (declaration.category !== undefined)
74
+ validateLocalized('Plugin permissions category', declaration.category, exports.PLUGIN_PERMISSION_LIMITS.labelLength);
75
+ const permissions = declaration.permissions;
76
+ if (!Array.isArray(permissions) || permissions.length === 0)
77
+ throw new Error('Plugin permissions: permissions must be a non-empty array');
78
+ if (permissions.length > exports.PLUGIN_PERMISSION_LIMITS.permissionsPerPlugin)
79
+ throw new Error(`Plugin permissions: at most ${exports.PLUGIN_PERMISSION_LIMITS.permissionsPerPlugin} keys`);
80
+ const seen = new Set();
81
+ for (const entry of permissions) {
82
+ if (!isPlainRecord(entry))
83
+ throw new Error('Plugin permission: each entry must be a plain object');
84
+ const key = entry.key;
85
+ const keyError = pluginPermissionKeyError(key);
86
+ if (keyError)
87
+ throw new Error(`Plugin permission "${String(key)}": key ${keyError}`);
88
+ const where = `Plugin permission "${key}"`;
89
+ if (seen.has(key))
90
+ throw new Error(`${where}: declared twice`);
91
+ seen.add(key);
92
+ for (const property of Object.keys(entry))
93
+ if (!['key', 'label', 'description', 'defaultRoles'].includes(property))
94
+ throw new Error(`${where}: unknown property "${property}"`);
95
+ validateLocalized(`${where}: label`, entry.label, exports.PLUGIN_PERMISSION_LIMITS.labelLength);
96
+ validateLocalized(`${where}: description`, entry.description, exports.PLUGIN_PERMISSION_LIMITS.descriptionLength);
97
+ if (entry.defaultRoles !== undefined) {
98
+ if (!Array.isArray(entry.defaultRoles))
99
+ throw new Error(`${where}: defaultRoles must be an array`);
100
+ for (const role of entry.defaultRoles)
101
+ if (!exports.PLUGIN_PERMISSION_DEFAULT_ROLES.includes(role))
102
+ throw new Error(`${where}: default role "${String(role)}" is not a system role (${exports.PLUGIN_PERMISSION_DEFAULT_ROLES.join(', ')})`);
103
+ }
104
+ }
105
+ return declaration;
106
+ }
107
+ //# sourceMappingURL=plugin-permissions.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"plugin-permissions.js","sourceRoot":"","sources":["../../../../../libs/plugins-backend-sdk/src/lib/plugin-permissions.ts"],"names":[],"mappings":"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"}
@@ -1,3 +1,4 @@
1
+ import type { PermissionKey } from './plugin-permissions';
1
2
  /** Result of {@link PluginResourceAccessContext.canStart}. */
2
3
  export interface PluginCanStartResult {
3
4
  /** The user may start a session on their own right now (introduction valid, no mandatory supervision). */
@@ -71,7 +72,7 @@ export interface PluginResourceAccessContext {
71
72
  */
72
73
  canSeeUsageAttribution(principal: PluginAccessPrincipal, resourceId: number): Promise<boolean>;
73
74
  /** 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
+ hasPermission(principal: PluginAccessPrincipal, permission: PermissionKey): Promise<boolean>;
75
76
  /**
76
77
  * Ids of resources the user is introduced to in the sense of canStart's introduction rule:
77
78
  * valid, not retraining-blocked direct or group introduction, introducer/maintainer role, or `resources.update`.
@@ -11,7 +11,22 @@ export declare enum SystemEvent {
11
11
  /** A user took over a running session. Fires for the NEW user. */
12
12
  RESOURCE_USAGE_SESSION_TAKEN_OVER = "RESOURCE_USAGE_SESSION_TAKEN_OVER",
13
13
  /** A session ended, either explicitly or because it was taken over. */
14
- RESOURCE_USAGE_SESSION_ENDED = "RESOURCE_USAGE_SESSION_ENDED"
14
+ RESOURCE_USAGE_SESSION_ENDED = "RESOURCE_USAGE_SESSION_ENDED",
15
+ /**
16
+ * The effective session limit of a resource changed (`maxParallelSessions`, or a type change that changes the
17
+ * limit). Fires after commit. See {@link ResourceSessionLimitChangedPayload}.
18
+ */
19
+ RESOURCE_SESSION_LIMIT_CHANGED = "RESOURCE_SESSION_LIMIT_CHANGED"
20
+ }
21
+ /** Emitted after the effective session limit of a resource changed (committed to the database). */
22
+ export interface ResourceSessionLimitChangedPayload {
23
+ resourceId: number;
24
+ /** Effective limit before the change (1 for doors and other non-machine types). */
25
+ previousLimit: number;
26
+ /** Effective limit after the change. */
27
+ newLimit: number;
28
+ /** The user who made the change, or null when the change was not made by a user. */
29
+ actorUserId: number | null;
15
30
  }
16
31
  /** Emitted after a maintenance window was created, updated or finished (committed to the database). */
17
32
  export interface MaintenanceChangedPayload {
@@ -76,6 +91,7 @@ export type SystemEventPayload = {
76
91
  [SystemEvent.RESOURCE_USAGE_SESSION_STARTED]: ResourceUsageSessionStartedPayload;
77
92
  [SystemEvent.RESOURCE_USAGE_SESSION_TAKEN_OVER]: ResourceUsageSessionTakenOverPayload;
78
93
  [SystemEvent.RESOURCE_USAGE_SESSION_ENDED]: ResourceUsageSessionEndedPayload;
94
+ [SystemEvent.RESOURCE_SESSION_LIMIT_CHANGED]: ResourceSessionLimitChangedPayload;
79
95
  };
80
96
  export type SystemEventResponse = {
81
97
  [E in SystemEvent]: null;
@@ -124,7 +140,9 @@ export declare enum PluginPermission {
124
140
  /** Register pre-start and session-end hooks that can confirm or block session starts. */
125
141
  ACCESS_HOOKS = "ACCESS_HOOKS",
126
142
  /** Send in-app, push and email notifications to users via notifications.dispatch(). */
127
- SEND_NOTIFICATIONS = "SEND_NOTIFICATIONS"
143
+ SEND_NOTIFICATIONS = "SEND_NOTIFICATIONS",
144
+ /** Use the Bluetooth radio of administrator-approved Attractap readers through context.ble, limited to the plugin's own BLE profiles. */
145
+ BLE_TRANSPORT = "BLE_TRANSPORT"
128
146
  }
129
147
  /**
130
148
  * Human-readable description of each permission, surfaced to admins and plugin
@@ -16,6 +16,11 @@ var SystemEvent;
16
16
  SystemEvent["RESOURCE_USAGE_SESSION_TAKEN_OVER"] = "RESOURCE_USAGE_SESSION_TAKEN_OVER";
17
17
  /** A session ended, either explicitly or because it was taken over. */
18
18
  SystemEvent["RESOURCE_USAGE_SESSION_ENDED"] = "RESOURCE_USAGE_SESSION_ENDED";
19
+ /**
20
+ * The effective session limit of a resource changed (`maxParallelSessions`, or a type change that changes the
21
+ * limit). Fires after commit. See {@link ResourceSessionLimitChangedPayload}.
22
+ */
23
+ SystemEvent["RESOURCE_SESSION_LIMIT_CHANGED"] = "RESOURCE_SESSION_LIMIT_CHANGED";
19
24
  })(SystemEvent || (exports.SystemEvent = SystemEvent = {}));
20
25
  /**
21
26
  * Discrete host capabilities a plugin may request in its manifest. A plugin can
@@ -50,6 +55,8 @@ var PluginPermission;
50
55
  PluginPermission["ACCESS_HOOKS"] = "ACCESS_HOOKS";
51
56
  /** Send in-app, push and email notifications to users via notifications.dispatch(). */
52
57
  PluginPermission["SEND_NOTIFICATIONS"] = "SEND_NOTIFICATIONS";
58
+ /** Use the Bluetooth radio of administrator-approved Attractap readers through context.ble, limited to the plugin's own BLE profiles. */
59
+ PluginPermission["BLE_TRANSPORT"] = "BLE_TRANSPORT";
53
60
  })(PluginPermission || (exports.PluginPermission = PluginPermission = {}));
54
61
  /**
55
62
  * Human-readable description of each permission, surfaced to admins and plugin
@@ -69,6 +76,7 @@ exports.PLUGIN_PERMISSION_DESCRIPTIONS = {
69
76
  [PluginPermission.READER_UI]: 'Show widgets on Attractap reader screens.',
70
77
  [PluginPermission.ACCESS_HOOKS]: 'Ask users for confirmation or block resource session starts through pre-start hooks.',
71
78
  [PluginPermission.SEND_NOTIFICATIONS]: 'Send notifications to users (in-app, push and email) under plugin-declared notification categories.',
79
+ [PluginPermission.BLE_TRANSPORT]: 'Use the Bluetooth radio of Attractap readers that an administrator opened for plugins, limited to the BLE profiles this plugin registers.',
72
80
  };
73
81
  /**
74
82
  * Returns true when the given string is a known PluginPermission value.