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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,83 @@
1
+ /** A user-facing label in every supported UI language. */
2
+ export interface PluginLocalizedLabel {
3
+ en: string;
4
+ de: string;
5
+ }
6
+ /**
7
+ * Notification category a plugin declares through
8
+ * {@link PluginBackendModule.notificationCategories}. The host namespaces it as
9
+ * `plugin.<pluginName>.<id>`, lists it in each user's notification preferences
10
+ * under the plugin's name and respects the user's per-channel choice (email, push,
11
+ * in-app toast) whenever the plugin dispatches under it.
12
+ */
13
+ export interface PluginNotificationCategory {
14
+ /** Short id, unique within the plugin. Lowercase letters, digits, `-`, `_`. */
15
+ id: string;
16
+ label: PluginLocalizedLabel;
17
+ }
18
+ /**
19
+ * Email template a plugin declares through {@link PluginBackendModule.emailTemplates}. It works like a core
20
+ * template: the host stores it per installation (key `plugin.<pluginName>.<id>`), lists it in the admin email
21
+ * template editor under the plugin's name, renders it inside the global layout, and admins can edit subject,
22
+ * body and translations. The declaration only seeds it, with its shipped translations: an installed template is
23
+ * never overwritten ("reset to default" restores the declared version). A malformed declaration, including a
24
+ * Handlebars syntax error, an unknown helper or a partial, quarantines the plugin.
25
+ *
26
+ * Texts use the template translation helper, `{{t "key" "English default" name=user.username}}`; the English
27
+ * default is inline and `translations.de` carries the German texts (every key used must be present).
28
+ */
29
+ export interface PluginEmailTemplate {
30
+ /** Short id, unique within the plugin. Lowercase letters, digits, `-`, `_`. */
31
+ id: string;
32
+ /** Name in the template list. */
33
+ label: PluginLocalizedLabel;
34
+ /** Variables the editor offers, e.g. `reservation.startTime`. `user.*`, `host.*` and `url` are always set. */
35
+ variables: string[];
36
+ /** Subject: a Handlebars string, usually one `t` call. */
37
+ subject: string;
38
+ /** Body: an MJML fragment without an `<mjml>` root (the host wraps it in the global layout). */
39
+ body: string;
40
+ /** Shipped translations per locale. `de` is required and must cover every `t` key of subject and body. */
41
+ translations: {
42
+ de: Record<string, string>;
43
+ } & Record<string, Record<string, string>>;
44
+ }
45
+ /** Sends one of the plugin's {@link PluginEmailTemplate}s with these variables (merged under `user`/`host`/`url`). */
46
+ export interface PluginNotificationEmailTemplate {
47
+ /** Short id of a template declared by this plugin via `emailTemplates`. */
48
+ template: string;
49
+ variables: Record<string, unknown>;
50
+ }
51
+ /** Custom email content. The host renders it inside the global email layout. */
52
+ export interface PluginNotificationRawEmail {
53
+ subject: string;
54
+ /** Trusted HTML fragment placed in the layout body. Takes precedence over text. */
55
+ html?: string;
56
+ /** Plain text. Used as the body (HTML-escaped) when html is omitted. */
57
+ text: string;
58
+ }
59
+ /** Prefer a template: admins cannot edit raw content. */
60
+ export type PluginNotificationEmail = PluginNotificationRawEmail | PluginNotificationEmailTemplate;
61
+ export interface PluginNotificationRequest {
62
+ /** Short id of a category declared by this plugin via `notificationCategories`. */
63
+ category: string;
64
+ /** User ids to notify. Unknown ids are skipped; duplicates are collapsed. */
65
+ recipients: number[];
66
+ title: string;
67
+ body: string;
68
+ /** In-app link target (relative to the application URL, e.g. `/resources/3`). */
69
+ url?: string;
70
+ severity?: 'info' | 'warning';
71
+ /** Collapses repeated push notifications that share the key. */
72
+ dedupeKey?: string;
73
+ /** When set, an email is sent to recipients whose preferences allow email for the category. A template is rendered in each recipient's language. */
74
+ email?: PluginNotificationEmail;
75
+ }
76
+ /** Notification dispatch for plugins. Requires the SEND_NOTIFICATIONS permission. */
77
+ export interface PluginNotificationsContext {
78
+ /**
79
+ * Dispatch a notification to users, honouring each user's channel preferences for the category.
80
+ * Rejects when the category was not declared by this plugin.
81
+ */
82
+ dispatch(request: PluginNotificationRequest): Promise<void>;
83
+ }
@@ -0,0 +1,3 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ //# sourceMappingURL=plugin-notifications.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"plugin-notifications.js","sourceRoot":"","sources":["../../../../../libs/plugins-backend-sdk/src/lib/plugin-notifications.ts"],"names":[],"mappings":""}
@@ -0,0 +1,89 @@
1
+ /** Result of {@link PluginResourceAccessContext.canStart}. */
2
+ export interface PluginCanStartResult {
3
+ /** The user may start a session on their own right now (introduction valid, no mandatory supervision). */
4
+ allowed: boolean;
5
+ /** The user may only start a session under a supervisor (mandatory, or not introduced yet). */
6
+ requiresSupervision: boolean;
7
+ /** The resource supports supervised sessions at all (supervision allowed or required). */
8
+ supervisionAllowed: boolean;
9
+ }
10
+ export interface PluginMaintenanceWindow {
11
+ maintenanceId: number;
12
+ resourceId: number;
13
+ startTime: Date;
14
+ /** Null for open-ended maintenance that is still running or announced without an end. */
15
+ endTime: Date | null;
16
+ reason: string | null;
17
+ }
18
+ export interface PluginActiveSession {
19
+ usageId: number;
20
+ userId: number;
21
+ startTime: Date;
22
+ }
23
+ /**
24
+ * A request-bound user: the authenticated principal of an HTTP request. `request.user` of an `@Auth()`
25
+ * route (`AuthenticatedUser`) fits as is.
26
+ */
27
+ export interface PluginAccessPrincipalUser {
28
+ id: number;
29
+ /**
30
+ * Permissions this request may use. For API-token requests core narrows them to the token's scope. When set,
31
+ * permission-based grants are limited to these permissions (intersected with the user's current RBAC
32
+ * permissions). Introducer/maintainer roles and introductions still apply, exactly as core applies them to an
33
+ * API-token request.
34
+ */
35
+ effectivePermissions?: Iterable<string>;
36
+ }
37
+ /**
38
+ * Whom an access query is about. Pass `request.user` for request-driven checks so API-token scopes apply. A plain
39
+ * user id resolves the user's full RBAC permissions; use it for background work such as schedulers.
40
+ */
41
+ export type PluginAccessPrincipal = number | PluginAccessPrincipalUser;
42
+ /**
43
+ * Read-only access and state queries over core authorization data. Requires the
44
+ * ACCESS_RESOURCES permission. All answers reuse the logic core uses to authorise
45
+ * session starts, so they never drift from what a start would actually allow.
46
+ *
47
+ * Methods that take a {@link PluginAccessPrincipal} accept either a user id or the request's user. Unknown users
48
+ * and unknown resources yield negative answers (`false`, all-false results, empty lists) rather than errors.
49
+ */
50
+ export interface PluginResourceAccessContext {
51
+ /**
52
+ * Whether the user may start a session on the resource. Covers direct and group
53
+ * introductions, retraining blocks, introducers/maintainers and `resources.update`,
54
+ * plus the resource's supervision mode. It does not look at live maintenance or health
55
+ * state; use getMaintenanceWindows for that. Returns all-false for an unknown user or resource.
56
+ */
57
+ canStart(principal: PluginAccessPrincipal, resourceId: number): Promise<PluginCanStartResult>;
58
+ /**
59
+ * Whether the user can manage maintenance of the resource: `resources.maintenance.manage`, or an
60
+ * introducer/maintainer role on the resource or one of its groups. Same check core's maintenance API uses.
61
+ */
62
+ canMaintain(principal: PluginAccessPrincipal, resourceId: number): Promise<boolean>;
63
+ /**
64
+ * Whether the user may see WHO is using the resource: the same rule core applies to the current user's name in
65
+ * the resource UI and API (`full` activity access). `resources.update` and `resources.access.manage` holders,
66
+ * people introduced to the machine (or its introducers/maintainers) and, when the instance shows activity to
67
+ * everyone, every reader qualify. Machines whose activity is hidden from the user, and unknown users or
68
+ * resources, answer `false`. A plugin that shows a person's name next to a machine (for example who holds a
69
+ * reservation) should follow this answer instead of keeping its own rule. Like core's rule it does not look at
70
+ * hidden resource groups or account state: check that the user may see the resource at all first.
71
+ */
72
+ canSeeUsageAttribution(principal: PluginAccessPrincipal, resourceId: number): Promise<boolean>;
73
+ /** Whether the user holds the RBAC permission (e.g. `resources.update`), limited to a request's scope. */
74
+ hasPermission(principal: PluginAccessPrincipal, permission: string): Promise<boolean>;
75
+ /**
76
+ * Ids of resources the user is introduced to in the sense of canStart's introduction rule:
77
+ * valid, not retraining-blocked direct or group introduction, introducer/maintainer role, or `resources.update`.
78
+ */
79
+ listResourceIdsIntroduced(principal: PluginAccessPrincipal): Promise<number[]>;
80
+ /** Ids of resources whose maintenance the user can manage. */
81
+ listResourceIdsMaintained(principal: PluginAccessPrincipal): Promise<number[]>;
82
+ /**
83
+ * Maintenance windows overlapping [from, to). A window covers [startTime, endTime ?? infinity), so
84
+ * open-ended maintenance counts from its start until it is finished.
85
+ */
86
+ getMaintenanceWindows(resourceId: number, from: Date, to: Date): Promise<PluginMaintenanceWindow[]>;
87
+ /** Currently running sessions on the resource, earliest first. */
88
+ getActiveSessions(resourceId: number): Promise<PluginActiveSession[]>;
89
+ }
@@ -0,0 +1,3 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ //# sourceMappingURL=plugin-resource-access.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"plugin-resource-access.js","sourceRoot":"","sources":["../../../../../libs/plugins-backend-sdk/src/lib/plugin-resource-access.ts"],"names":[],"mappings":""}
@@ -1,7 +1,66 @@
1
- import { Resource, User } from '@attraccess/database-entities';
1
+ import { Resource, ResourceHealthStatus, User } from '@attraccess/database-entities';
2
2
  export declare enum SystemEvent {
3
3
  RESOURCE_USAGE_STARTED = "RESOURCE_USAGE_STARTED",
4
- RESOURCE_USAGE_ENDED = "RESOURCE_USAGE_ENDED"
4
+ RESOURCE_USAGE_ENDED = "RESOURCE_USAGE_ENDED",
5
+ /** A maintenance window was created, updated or finished. See {@link MaintenanceChangedPayload}. */
6
+ MAINTENANCE_CHANGED = "MAINTENANCE_CHANGED",
7
+ /** A resource health entry changed status. See {@link ResourceHealthChangedPayload}. */
8
+ RESOURCE_HEALTH_CHANGED = "RESOURCE_HEALTH_CHANGED",
9
+ /** A user started a session on an idle resource (not a takeover). */
10
+ RESOURCE_USAGE_SESSION_STARTED = "RESOURCE_USAGE_SESSION_STARTED",
11
+ /** A user took over a running session. Fires for the NEW user. */
12
+ RESOURCE_USAGE_SESSION_TAKEN_OVER = "RESOURCE_USAGE_SESSION_TAKEN_OVER",
13
+ /** A session ended, either explicitly or because it was taken over. */
14
+ RESOURCE_USAGE_SESSION_ENDED = "RESOURCE_USAGE_SESSION_ENDED"
15
+ }
16
+ /** Emitted after a maintenance window was created, updated or finished (committed to the database). */
17
+ export interface MaintenanceChangedPayload {
18
+ resourceId: number;
19
+ maintenanceId: number;
20
+ /**
21
+ * Core currently emits only `created` and `finished`; maintenance windows have no edit path yet.
22
+ * `updated` is reserved for forward compatibility, so handle it like `created` (re-read the window).
23
+ */
24
+ action: 'created' | 'updated' | 'finished';
25
+ startTime: Date;
26
+ /** Null while the maintenance is open-ended (no end set, not finished). */
27
+ endTime: Date | null;
28
+ }
29
+ /** Emitted after a resource health entry changed status. Only real status transitions fire. */
30
+ export interface ResourceHealthChangedPayload {
31
+ resourceId: number;
32
+ status: ResourceHealthStatus;
33
+ previousStatus: ResourceHealthStatus | null;
34
+ reason: string | null;
35
+ /** Identifier of the health entry (resources can carry several independent entries). */
36
+ identifier: string;
37
+ }
38
+ export interface ResourceUsageSessionStartedPayload {
39
+ resourceId: number;
40
+ usageId: number;
41
+ userId: number;
42
+ startTime: Date;
43
+ /** Set when the session was started under supervision. */
44
+ supervisorUserId: number | null;
45
+ }
46
+ export interface ResourceUsageSessionTakenOverPayload {
47
+ resourceId: number;
48
+ /** The new session. */
49
+ usageId: number;
50
+ /** The user who took over (the new session owner). */
51
+ userId: number;
52
+ startTime: Date;
53
+ previousUsageId: number;
54
+ previousUserId: number;
55
+ }
56
+ export interface ResourceUsageSessionEndedPayload {
57
+ resourceId: number;
58
+ usageId: number;
59
+ userId: number;
60
+ startTime: Date;
61
+ endTime: Date | null;
62
+ /** 'taken_over' when the session ended because another user took it over. */
63
+ reason: 'ended' | 'taken_over';
5
64
  }
6
65
  export type SystemEventPayload = {
7
66
  [SystemEvent.RESOURCE_USAGE_STARTED]: {
@@ -12,10 +71,14 @@ export type SystemEventPayload = {
12
71
  resource: Resource;
13
72
  user: User;
14
73
  };
74
+ [SystemEvent.MAINTENANCE_CHANGED]: MaintenanceChangedPayload;
75
+ [SystemEvent.RESOURCE_HEALTH_CHANGED]: ResourceHealthChangedPayload;
76
+ [SystemEvent.RESOURCE_USAGE_SESSION_STARTED]: ResourceUsageSessionStartedPayload;
77
+ [SystemEvent.RESOURCE_USAGE_SESSION_TAKEN_OVER]: ResourceUsageSessionTakenOverPayload;
78
+ [SystemEvent.RESOURCE_USAGE_SESSION_ENDED]: ResourceUsageSessionEndedPayload;
15
79
  };
16
80
  export type SystemEventResponse = {
17
- [SystemEvent.RESOURCE_USAGE_STARTED]: null;
18
- [SystemEvent.RESOURCE_USAGE_ENDED]: null;
81
+ [E in SystemEvent]: null;
19
82
  };
20
83
  /**
21
84
  * Typed handler a plugin registers for a given SystemEvent. It receives the
@@ -55,7 +118,13 @@ export declare enum PluginPermission {
55
118
  /** Start flows from plugin-declared trigger nodes via flows.trigger(). */
56
119
  TRIGGER_FLOWS = "TRIGGER_FLOWS",
57
120
  /** Encrypt and decrypt plugin-owned secret material through the host key service. */
58
- MANAGE_SECRETS = "MANAGE_SECRETS"
121
+ MANAGE_SECRETS = "MANAGE_SECRETS",
122
+ /** Contribute reader UI slots and call readerUi.invalidate(). */
123
+ READER_UI = "READER_UI",
124
+ /** Register pre-start and session-end hooks that can confirm or block session starts. */
125
+ ACCESS_HOOKS = "ACCESS_HOOKS",
126
+ /** Send in-app, push and email notifications to users via notifications.dispatch(). */
127
+ SEND_NOTIFICATIONS = "SEND_NOTIFICATIONS"
59
128
  }
60
129
  /**
61
130
  * Human-readable description of each permission, surfaced to admins and plugin
@@ -6,6 +6,16 @@ var SystemEvent;
6
6
  (function (SystemEvent) {
7
7
  SystemEvent["RESOURCE_USAGE_STARTED"] = "RESOURCE_USAGE_STARTED";
8
8
  SystemEvent["RESOURCE_USAGE_ENDED"] = "RESOURCE_USAGE_ENDED";
9
+ /** A maintenance window was created, updated or finished. See {@link MaintenanceChangedPayload}. */
10
+ SystemEvent["MAINTENANCE_CHANGED"] = "MAINTENANCE_CHANGED";
11
+ /** A resource health entry changed status. See {@link ResourceHealthChangedPayload}. */
12
+ SystemEvent["RESOURCE_HEALTH_CHANGED"] = "RESOURCE_HEALTH_CHANGED";
13
+ /** A user started a session on an idle resource (not a takeover). */
14
+ SystemEvent["RESOURCE_USAGE_SESSION_STARTED"] = "RESOURCE_USAGE_SESSION_STARTED";
15
+ /** A user took over a running session. Fires for the NEW user. */
16
+ SystemEvent["RESOURCE_USAGE_SESSION_TAKEN_OVER"] = "RESOURCE_USAGE_SESSION_TAKEN_OVER";
17
+ /** A session ended, either explicitly or because it was taken over. */
18
+ SystemEvent["RESOURCE_USAGE_SESSION_ENDED"] = "RESOURCE_USAGE_SESSION_ENDED";
9
19
  })(SystemEvent || (exports.SystemEvent = SystemEvent = {}));
10
20
  /**
11
21
  * Discrete host capabilities a plugin may request in its manifest. A plugin can
@@ -34,6 +44,12 @@ var PluginPermission;
34
44
  PluginPermission["TRIGGER_FLOWS"] = "TRIGGER_FLOWS";
35
45
  /** Encrypt and decrypt plugin-owned secret material through the host key service. */
36
46
  PluginPermission["MANAGE_SECRETS"] = "MANAGE_SECRETS";
47
+ /** Contribute reader UI slots and call readerUi.invalidate(). */
48
+ PluginPermission["READER_UI"] = "READER_UI";
49
+ /** Register pre-start and session-end hooks that can confirm or block session starts. */
50
+ PluginPermission["ACCESS_HOOKS"] = "ACCESS_HOOKS";
51
+ /** Send in-app, push and email notifications to users via notifications.dispatch(). */
52
+ PluginPermission["SEND_NOTIFICATIONS"] = "SEND_NOTIFICATIONS";
37
53
  })(PluginPermission || (exports.PluginPermission = PluginPermission = {}));
38
54
  /**
39
55
  * Human-readable description of each permission, surfaced to admins and plugin
@@ -41,7 +57,7 @@ var PluginPermission;
41
57
  */
42
58
  exports.PLUGIN_PERMISSION_DESCRIPTIONS = {
43
59
  [PluginPermission.READ_USERS]: 'Read user accounts from the database.',
44
- [PluginPermission.ACCESS_RESOURCES]: 'Read and write resources from the database.',
60
+ [PluginPermission.ACCESS_RESOURCES]: 'Read and write resources from the database and query resource access, maintenance windows and active sessions.',
45
61
  [PluginPermission.READ_SETTINGS]: 'Read application settings from the database.',
46
62
  [PluginPermission.DATABASE_ACCESS]: 'Access the raw database connection and any other entity repository.',
47
63
  [PluginPermission.EMIT_EVENTS]: 'Publish events on the shared application event bus.',
@@ -50,6 +66,9 @@ exports.PLUGIN_PERMISSION_DESCRIPTIONS = {
50
66
  [PluginPermission.ACCESS_MQTT_SERVERS]: "Read an MQTT server's connection configuration and resolved credentials.",
51
67
  [PluginPermission.TRIGGER_FLOWS]: 'Start flows from plugin-declared trigger nodes.',
52
68
  [PluginPermission.MANAGE_SECRETS]: 'Encrypt and decrypt plugin-owned secret material through the host key service.',
69
+ [PluginPermission.READER_UI]: 'Show widgets on Attractap reader screens.',
70
+ [PluginPermission.ACCESS_HOOKS]: 'Ask users for confirmation or block resource session starts through pre-start hooks.',
71
+ [PluginPermission.SEND_NOTIFICATIONS]: 'Send notifications to users (in-app, push and email) under plugin-declared notification categories.',
53
72
  };
54
73
  /**
55
74
  * Returns true when the given string is a known PluginPermission value.
@@ -1 +1 @@
1
- {"version":3,"file":"plugin.interface.js","sourceRoot":"","sources":["../../../../../libs/plugins-backend-sdk/src/lib/plugin.interface.ts"],"names":[],"mappings":";;;AAkFA,gDAEC;AAlFD,IAAY,WAGX;AAHD,WAAY,WAAW;IACrB,gEAAiD,CAAA;IACjD,4DAA6C,CAAA;AAC/C,CAAC,EAHW,WAAW,2BAAX,WAAW,QAGtB;AA6BD;;;;GAIG;AACH,IAAY,gBAqBX;AArBD,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;IAC3C,0EAA0E;IAC1E,mDAA+B,CAAA;IAC/B,qFAAqF;IACrF,qDAAiC,CAAA;AACnC,CAAC,EArBW,gBAAgB,gCAAhB,gBAAgB,QAqB3B;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;IAClH,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,iDAAiD;IACnF,CAAC,gBAAgB,CAAC,cAAc,CAAC,EAAE,gFAAgF;CACpH,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"}
1
+ {"version":3,"file":"plugin.interface.js","sourceRoot":"","sources":["../../../../../libs/plugins-backend-sdk/src/lib/plugin.interface.ts"],"names":[],"mappings":";;;AAkKA,gDAEC;AAlKD,IAAY,WAaX;AAbD,WAAY,WAAW;IACrB,gEAAiD,CAAA;IACjD,4DAA6C,CAAA;IAC7C,oGAAoG;IACpG,0DAA2C,CAAA;IAC3C,wFAAwF;IACxF,kEAAmD,CAAA;IACnD,qEAAqE;IACrE,gFAAiE,CAAA;IACjE,kEAAkE;IAClE,sFAAuE,CAAA;IACvE,uEAAuE;IACvE,4EAA6D,CAAA;AAC/D,CAAC,EAbW,WAAW,2BAAX,WAAW,QAatB;AAuFD;;;;GAIG;AACH,IAAY,gBA2BX;AA3BD,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;IAC3C,0EAA0E;IAC1E,mDAA+B,CAAA;IAC/B,qFAAqF;IACrF,qDAAiC,CAAA;IACjC,iEAAiE;IACjE,2CAAuB,CAAA;IACvB,yFAAyF;IACzF,iDAA6B,CAAA;IAC7B,uFAAuF;IACvF,6DAAyC,CAAA;AAC3C,CAAC,EA3BW,gBAAgB,gCAAhB,gBAAgB,QA2B3B;AAED;;;GAGG;AACU,QAAA,8BAA8B,GAAqC;IAC9E,CAAC,gBAAgB,CAAC,UAAU,CAAC,EAAE,uCAAuC;IACtE,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,EACjC,gHAAgH;IAClH,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;IAClH,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,iDAAiD;IACnF,CAAC,gBAAgB,CAAC,cAAc,CAAC,EAAE,gFAAgF;IACnH,CAAC,gBAAgB,CAAC,SAAS,CAAC,EAAE,2CAA2C;IACzE,CAAC,gBAAgB,CAAC,YAAY,CAAC,EAC7B,sFAAsF;IACxF,CAAC,gBAAgB,CAAC,kBAAkB,CAAC,EACnC,qGAAqG;CACxG,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"}
@@ -0,0 +1,317 @@
1
+ /**
2
+ * Reader UI schema v1 and the pre-start / session-end hook contract.
3
+ *
4
+ * Plugins describe UI as plain data. Nothing here runs on the reader. The host
5
+ * validates, sanitizes (Latin-1) and size-checks everything before it is sent.
6
+ * The firmware mirrors the constants in `display/ui/ui_schema.hpp`; a Jest
7
+ * parity test keeps both in sync.
8
+ */
9
+ import type { PluginAccessPrincipal } from './plugin-resource-access';
10
+ export type ReaderUiTone = 'primary' | 'success' | 'warning' | 'danger';
11
+ export type ReaderUiIconName = 'ok' | 'warning' | 'bell' | 'lock' | 'clock';
12
+ export type ReaderUiTextStyle = 'title' | 'body' | 'small';
13
+ export type ReaderUiNode = {
14
+ t: 'col' | 'row';
15
+ c?: ReaderUiNode[];
16
+ gap?: number;
17
+ pad?: number;
18
+ fill?: boolean;
19
+ tone?: ReaderUiTone;
20
+ } | {
21
+ t: 'text';
22
+ text: string;
23
+ style?: ReaderUiTextStyle;
24
+ fill?: boolean;
25
+ } | {
26
+ t: 'badge';
27
+ text: string;
28
+ tone?: ReaderUiTone;
29
+ } | {
30
+ t: 'icon';
31
+ name: ReaderUiIconName;
32
+ tone?: ReaderUiTone;
33
+ }
34
+ /** Steps only. Slot trees must not contain buttons. */
35
+ | {
36
+ t: 'button';
37
+ id: string;
38
+ text: string;
39
+ variant?: 'primary' | 'secondary';
40
+ } | {
41
+ t: 'progress';
42
+ value: number;
43
+ tone?: ReaderUiTone;
44
+ }
45
+ /** Plugin-facing form takes a Date; the wire form carries epoch milliseconds in `toMs`. */
46
+ | {
47
+ t: 'countdown';
48
+ to: Date;
49
+ tone?: ReaderUiTone;
50
+ } | {
51
+ t: 'spacer';
52
+ h?: number;
53
+ };
54
+ /** Wire form of a node tree: `countdown.to` is replaced by `toMs`. */
55
+ export type ReaderUiWireNode = Exclude<ReaderUiNode, {
56
+ t: 'countdown' | 'col' | 'row';
57
+ }> | {
58
+ t: 'col' | 'row';
59
+ c?: ReaderUiWireNode[];
60
+ gap?: number;
61
+ pad?: number;
62
+ fill?: boolean;
63
+ tone?: ReaderUiTone;
64
+ } | {
65
+ t: 'countdown';
66
+ toMs: number;
67
+ tone?: ReaderUiTone;
68
+ };
69
+ export declare const READER_UI_SCHEMA_VERSION = 1;
70
+ export declare const READER_UI_COMPONENTS: readonly ["col", "row", "text", "badge", "icon", "button", "progress", "countdown", "spacer"];
71
+ export type ReaderUiComponent = (typeof READER_UI_COMPONENTS)[number];
72
+ export declare const READER_UI_TONES: readonly ReaderUiTone[];
73
+ export declare const READER_UI_ICONS: readonly ReaderUiIconName[];
74
+ export declare const READER_UI_TEXT_STYLES: readonly ReaderUiTextStyle[];
75
+ export declare const READER_UI_SLOTS: {
76
+ readonly RESOURCE_LIST_ROW_STATUS: "resourceList.row.status";
77
+ readonly RESOURCE_DETAILS_HEADER: "resource.details.header";
78
+ readonly RESOURCE_DETAILS_BODY: "resource.details.body";
79
+ readonly RESOURCE_DETAILS_SESSION: "resource.details.session";
80
+ };
81
+ export type ReaderUiSlotId = (typeof READER_UI_SLOTS)[keyof typeof READER_UI_SLOTS];
82
+ export declare const READER_UI_SLOT_IDS: readonly ReaderUiSlotId[];
83
+ /** Node budget per slot. The list row slot takes a single text or badge. */
84
+ export declare const READER_UI_SLOT_NODE_BUDGET: Record<ReaderUiSlotId, number>;
85
+ export declare const READER_UI_STEP_KINDS: readonly ["confirm", "choose", "info"];
86
+ export type ReaderUiStepKind = (typeof READER_UI_STEP_KINDS)[number];
87
+ export type ReaderUiStepRole = 'cancel' | 'confirm' | 'ok' | 'choice';
88
+ export declare const READER_UI_LIMITS: {
89
+ /** UTF-8 bytes of the sanitized UI payload. */
90
+ readonly maxPayloadBytes: 3072;
91
+ /** Whole websocket frame; legacy token readers cannot reassemble. */
92
+ readonly maxFrameBytes: 4096;
93
+ readonly maxNodes: 32;
94
+ readonly maxDepth: 5;
95
+ readonly maxLiveNodes: 64;
96
+ readonly maxTextChars: 80;
97
+ readonly maxLabelBytes: 31;
98
+ readonly maxListRowChars: 24;
99
+ readonly maxChoices: 4;
100
+ readonly maxSlotContributionsPerResource: 8;
101
+ readonly idPattern: RegExp;
102
+ };
103
+ export declare const READER_UI_TIMING: {
104
+ readonly stepDefaultTtlSec: 60;
105
+ readonly stepMaxTtlSec: 120;
106
+ readonly stepGraceSec: 5;
107
+ readonly postStopDefaultTtlSec: 15;
108
+ readonly postStopMaxTtlSec: 30;
109
+ readonly hookDefaultTimeoutMs: 1500;
110
+ readonly hookMaxTimeoutMs: 3000;
111
+ readonly breakerThreshold: 5;
112
+ readonly breakerProbeAfterMs: 60000;
113
+ readonly crashLoopSuspendMs: number;
114
+ readonly slotUpdateMinIntervalMs: 2000;
115
+ };
116
+ /**
117
+ * Strings that only the host may show (core status). Plugin text is rejected when it equals one after lower-casing,
118
+ * collapsing whitespace and stripping non-letters at both ends.
119
+ */
120
+ export declare const READER_UI_RESERVED_STATUS_STRINGS: readonly string[];
121
+ export type NoScreenPolicy = 'block' | 'card-confirm' | 'allow-with-warning';
122
+ export declare const NO_SCREEN_POLICIES: readonly NoScreenPolicy[];
123
+ export declare const DEFAULT_NO_SCREEN_POLICY: NoScreenPolicy;
124
+ export type HookFailurePolicy = 'fail-closed' | 'fail-open';
125
+ /** Reset reasons shared with READER_CRASH_REPORT. */
126
+ export declare const PANIC_CLASS_RESET_REASONS: readonly ["PANIC", "INT_WDT", "TASK_WDT", "WDT", "CPU_LOCKUP"];
127
+ /** What a reader reports in `READER_FIRMWARE_INFO.capabilities.ui`. Missing = schemaVersion 0. */
128
+ export interface ReaderUiCapabilities {
129
+ schemaVersion: number;
130
+ components: string[];
131
+ slots: string[];
132
+ /** Touch: confirm/choose/info. Lite: [] or ['card-confirm']. */
133
+ steps: string[];
134
+ maxPayloadBytes: number;
135
+ maxNodes: number;
136
+ maxDepth: number;
137
+ maxLiveNodes: number;
138
+ display: {
139
+ w: number;
140
+ h: number;
141
+ touch: boolean;
142
+ } | null;
143
+ input: {
144
+ touch: boolean;
145
+ buttons: number;
146
+ cardHold: boolean;
147
+ };
148
+ feedback: {
149
+ leds: boolean;
150
+ beeper: boolean;
151
+ };
152
+ charset: 'latin1';
153
+ images: boolean;
154
+ }
155
+ export declare const READER_UI_CAPABILITIES_NONE: ReaderUiCapabilities;
156
+ export interface ReaderUiContext {
157
+ readerId: number;
158
+ resourceId: number;
159
+ /** Set whenever a card session is live; never for a signed-out reader. */
160
+ userId?: number;
161
+ /**
162
+ * The resource has an active usage visible on this reader. The reader shows `resource.details.session` only
163
+ * while this is true, so a provider that wants a fact in one block puts it in the session slot when this is true
164
+ * and in the details body otherwise. The host re-evaluates the provider when a usage starts, ends or is taken
165
+ * over. Optional for compatibility: when unset, treat it as `false`.
166
+ */
167
+ sessionActive?: boolean;
168
+ capabilities: ReaderUiCapabilities;
169
+ language: 'en' | 'de';
170
+ }
171
+ export interface ReaderSlotContribution {
172
+ slotId: ReaderUiSlotId;
173
+ /** Plugin-local, unique per slot and resource. */
174
+ key: string;
175
+ tree: ReaderUiNode;
176
+ /** The host re-evaluates the provider at this time and removes the contribution. */
177
+ expiresAt?: Date;
178
+ /** Sent instead of `tree` when the reader cannot render it. */
179
+ fallback?: {
180
+ text: string;
181
+ tone?: ReaderUiTone;
182
+ };
183
+ }
184
+ export interface ReaderUiProvider {
185
+ getSlotContributions(ctx: ReaderUiContext): ReaderSlotContribution[] | Promise<ReaderSlotContribution[]>;
186
+ /**
187
+ * The IANA time zone (e.g. `Europe/Berlin`) this plugin writes times in on readers for the resource, or `undefined`
188
+ * for no opinion. The host sends one zone per reader, so the reader's clock and the plugin's texts agree: the first
189
+ * valid zone in host order wins (the reader's resources by id, and for each resource the plugins in host order,
190
+ * alphabetically by plugin name; a slower plugin that answers within the time limit still wins over a faster one
191
+ * ranked lower), otherwise the server's `TZ` applies. An invalid name is ignored; two different zones for one reader
192
+ * raise an admin alert. Called with the slot timeout; an error or timeout counts as no opinion. Call
193
+ * `readerUi.invalidate` when the zone changes.
194
+ */
195
+ getTimeZone?(ctx: {
196
+ readerId: number;
197
+ resourceId: number;
198
+ }): string | undefined | Promise<string | undefined>;
199
+ }
200
+ export type PreStartOrigin = 'web' | 'api' | 'reader' | 'supervision';
201
+ export interface PreStartContext {
202
+ resourceId: number;
203
+ userId: number;
204
+ /**
205
+ * The starter as a `resourceAccess` principal. Web and API starts carry the request's permissions (an API token's
206
+ * scope), reader and supervision starts the plain user id. Pass it to `resourceAccess` instead of `userId`, so
207
+ * permission checks in the hook apply the same scope as core's own start checks.
208
+ */
209
+ principal: PluginAccessPrincipal;
210
+ action: 'start' | 'takeover';
211
+ projectId?: number;
212
+ origin: PreStartOrigin;
213
+ /** Only this plugin's step keys, checked by the host. */
214
+ confirmedStepKeys: string[];
215
+ /** Language for texts: the card user's on a reader, the user's preferred language elsewhere. */
216
+ language: 'en' | 'de';
217
+ now: Date;
218
+ }
219
+ export interface PluginConfirmation {
220
+ /** Stable per plugin; the host issues a random stepId per step. */
221
+ stepKey: string;
222
+ title: string;
223
+ body: string;
224
+ tone?: ReaderUiTone;
225
+ confirmLabel?: string;
226
+ cancelLabel?: string;
227
+ countdownTo?: Date;
228
+ /** Host clamps to [10, 120]. */
229
+ expiresInSec?: number;
230
+ /** Plugin default for readers without a screen. */
231
+ noScreenPolicy?: NoScreenPolicy;
232
+ }
233
+ export interface PluginBlockReason {
234
+ code: string;
235
+ title: string;
236
+ body: string;
237
+ }
238
+ export type PreStartResult = {
239
+ decision: 'allow';
240
+ } | {
241
+ decision: 'confirm';
242
+ confirmation: PluginConfirmation;
243
+ } | {
244
+ decision: 'block';
245
+ reason: PluginBlockReason;
246
+ };
247
+ export type PreStartHook = (ctx: PreStartContext) => PreStartResult | Promise<PreStartResult>;
248
+ export interface StartBlockedContext {
249
+ resourceId: number;
250
+ /** The user looking at the resource. Apply your own visibility rules before naming anybody in the reason. */
251
+ userId: number;
252
+ /** The viewer as a `resourceAccess` principal, with the request's permissions (an API token's scope). */
253
+ principal: PluginAccessPrincipal;
254
+ /** Language for texts: the user's preferred language. */
255
+ language: 'en' | 'de';
256
+ now: Date;
257
+ }
258
+ /** A start that is refused right now. Same reason shape as a `preStartHook` block. */
259
+ export interface StartBlockedState {
260
+ reason: PluginBlockReason;
261
+ /** When the block ends, if known. The host UI refreshes itself then and shows the time. */
262
+ until?: Date;
263
+ }
264
+ /**
265
+ * Query-side counterpart of `preStartHook`: tells the UI that a start by this user is blocked right now, so it
266
+ * can show the reason in place of the start button instead of letting the user press it. Return null when
267
+ * nothing blocks. It is informational only: `preStartHook` stays the authoritative gate and must still block.
268
+ * Keep it cheap and side-effect free; it is called whenever a resource page is open. Failures and timeouts
269
+ * count as "not blocked". Requires ACCESS_HOOKS.
270
+ */
271
+ export type StartBlockedQuery = (ctx: StartBlockedContext) => StartBlockedState | null | Promise<StartBlockedState | null>;
272
+ /** Lets a plugin tell the host UI that the answer of its `startBlockedQuery` may have changed. */
273
+ export interface PluginStartBlockedApi {
274
+ /** Open resource pages ask again. Call it when bookings or rules that decide the block change. */
275
+ invalidate(scope: {
276
+ resourceId: number;
277
+ }): void;
278
+ }
279
+ export interface SessionEndContext {
280
+ resourceId: number;
281
+ userId: number;
282
+ sessionId: number;
283
+ origin: 'web' | 'api' | 'reader';
284
+ /** Language for texts: the card user's on a reader, the user's preferred language elsewhere. */
285
+ language: 'en' | 'de';
286
+ now: Date;
287
+ }
288
+ export interface PluginChoice {
289
+ stepKey: string;
290
+ title: string;
291
+ body: string;
292
+ /** Max 4. */
293
+ choices: {
294
+ id: string;
295
+ label: string;
296
+ }[];
297
+ /** Applied on timeout, disconnect, cancel and readers without a screen. */
298
+ defaultOnTimeout: string;
299
+ /** How long the reader shows the question. Default 15, host clamps to [5, 30]. */
300
+ expiresInSec?: number;
301
+ /** Called once with the answer or the default; runs with the hook timeout, errors are logged. */
302
+ onAnswer(choiceId: string): void | Promise<void>;
303
+ }
304
+ export type SessionEndResult = {
305
+ decision: 'none';
306
+ } | {
307
+ decision: 'choose';
308
+ choice: PluginChoice;
309
+ };
310
+ export type SessionEndHook = (ctx: SessionEndContext) => SessionEndResult | Promise<SessionEndResult>;
311
+ export interface PluginReaderUiApi {
312
+ /** Re-evaluate and push contributions for a resource or reader. */
313
+ invalidate(scope: {
314
+ resourceId?: number;
315
+ readerId?: number;
316
+ }): void;
317
+ }