@deveye/types 0.19.2 → 0.20.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.
- package/package.json +1 -1
- package/src/domain/featureRegistry.test.ts +33 -0
- package/src/domain/featureRegistry.ts +45 -2
- package/src/domain/home.ts +2 -1
- package/src/domain/live.ts +1 -0
- package/src/domain/maintenance.ts +50 -0
- package/src/domain/notifications.ts +2 -1
- package/src/domain/sharing.ts +9 -1
- package/src/domain/user.ts +4 -1
- package/src/domain/workspaceRole.ts +8 -1
- package/src/features/admin.ts +70 -1
- package/src/features/domain.ts +16 -1
- package/src/http/auth.ts +7 -1
- package/src/index.ts +21 -1
- package/src/protocol/error.ts +4 -1
- package/src/sdk/client-ambient.d.ts +46 -4
- package/src/sdk/manifest.test.ts +23 -2
- package/src/sdk/manifest.ts +20 -0
- package/src/sdk/server.ts +29 -3
package/package.json
CHANGED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import assert from 'node:assert/strict';
|
|
2
|
+
import { test } from 'node:test';
|
|
3
|
+
|
|
4
|
+
import { FEATURE_REGISTRY } from './featureRegistry';
|
|
5
|
+
|
|
6
|
+
test('every native that notifies says when, and none says it without notifying', () => {
|
|
7
|
+
for (const feature of FEATURE_REGISTRY) {
|
|
8
|
+
if (feature.notifies) {
|
|
9
|
+
assert.ok(
|
|
10
|
+
feature.notifications?.hint.trim(),
|
|
11
|
+
`${feature.id}: notifies without notifications.hint`
|
|
12
|
+
);
|
|
13
|
+
} else {
|
|
14
|
+
assert.equal(
|
|
15
|
+
feature.notifications,
|
|
16
|
+
undefined,
|
|
17
|
+
`${feature.id}: notifications.hint without notifies`
|
|
18
|
+
);
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
test('no registry sentence carries an em dash', () => {
|
|
24
|
+
for (const feature of FEATURE_REGISTRY) {
|
|
25
|
+
for (const text of [
|
|
26
|
+
feature.description,
|
|
27
|
+
feature.sources?.hint,
|
|
28
|
+
feature.notifications?.hint
|
|
29
|
+
]) {
|
|
30
|
+
if (text) assert.equal(text.includes('—'), false, `${feature.id}: « ${text} »`);
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
});
|
|
@@ -16,7 +16,7 @@ export interface FeatureDescriptor {
|
|
|
16
16
|
/** Intitulé d'interface, en français (anglais pour un module externe). Jamais l'identifiant technique. */
|
|
17
17
|
label: string;
|
|
18
18
|
/**
|
|
19
|
-
* Ce que le droit ouvre, en une phrase
|
|
19
|
+
* Ce que le droit ouvre, en une phrase, affichée sous la ligne de la
|
|
20
20
|
* fonctionnalité dans l'écran des rôles. Dit ce que `read` et `write`
|
|
21
21
|
* recouvrent quand la différence n'est pas évidente.
|
|
22
22
|
*/
|
|
@@ -55,6 +55,12 @@ export interface FeatureDescriptor {
|
|
|
55
55
|
* l'onglet « Notifications » (voir `notifies`).
|
|
56
56
|
*/
|
|
57
57
|
sources?: { hint: string };
|
|
58
|
+
/**
|
|
59
|
+
* La phrase de tête de l'onglet Notifications : QUAND la fonctionnalité
|
|
60
|
+
* prévient. Sans elle, l'onglet liste des canaux sans dire à quoi ils
|
|
61
|
+
* servent. Exigée dès que `notifies` est vrai.
|
|
62
|
+
*/
|
|
63
|
+
notifications?: { hint: string };
|
|
58
64
|
/**
|
|
59
65
|
* Un de ses éléments peut-il être rendu visible depuis un autre espace ?
|
|
60
66
|
* Décidé par le chiffrement : un élément partagé reste chiffré sous la clé
|
|
@@ -91,6 +97,9 @@ export const FEATURE_REGISTRY: readonly (FeatureDescriptor & { id: WorkspaceFeat
|
|
|
91
97
|
'Lecture : constats et posture. Écriture : acquitter, régler, relancer un relevé.',
|
|
92
98
|
icon: 'shield',
|
|
93
99
|
notifies: true,
|
|
100
|
+
notifications: {
|
|
101
|
+
hint: 'Envoyées à chaque nouveau constat de la Sentinelle : une machine suspecte, une dérive de configuration, une règle enfreinte.'
|
|
102
|
+
},
|
|
94
103
|
hasItems: false,
|
|
95
104
|
shareTier: 'never'
|
|
96
105
|
},
|
|
@@ -144,6 +153,9 @@ export const FEATURE_REGISTRY: readonly (FeatureDescriptor & { id: WorkspaceFeat
|
|
|
144
153
|
'Lecture : disponibilité et incidents. Écriture : déclarer et régler les services.',
|
|
145
154
|
icon: 'uptime',
|
|
146
155
|
notifies: true,
|
|
156
|
+
notifications: {
|
|
157
|
+
hint: 'Envoyées à chaque bascule d’un service surveillé : hors ligne (avec l’heure et l’erreur) puis retour en ligne (avec la durée de la panne).'
|
|
158
|
+
},
|
|
147
159
|
hasItems: true,
|
|
148
160
|
itemNoun: 'service',
|
|
149
161
|
shareTier: 'open'
|
|
@@ -189,6 +201,9 @@ export const FEATURE_REGISTRY: readonly (FeatureDescriptor & { id: WorkspaceFeat
|
|
|
189
201
|
'Lecture : cibles et historique. Écriture : poser la clé d’API et déclencher une mise en production.',
|
|
190
202
|
icon: 'rocket',
|
|
191
203
|
notifies: true,
|
|
204
|
+
notifications: {
|
|
205
|
+
hint: 'Envoyées à l’atterrissage d’un déploiement, échec comme succès, y compris ceux lancés depuis Dokploy, une CI ou un push git.'
|
|
206
|
+
},
|
|
192
207
|
hasItems: true,
|
|
193
208
|
itemNoun: 'cible',
|
|
194
209
|
itemNounGender: 'f',
|
|
@@ -204,6 +219,9 @@ export const FEATURE_REGISTRY: readonly (FeatureDescriptor & { id: WorkspaceFeat
|
|
|
204
219
|
'Lecture : état et exploration. Écriture : déclarer une base, ses accès et ses alertes.',
|
|
205
220
|
icon: 'database',
|
|
206
221
|
notifies: true,
|
|
222
|
+
notifications: {
|
|
223
|
+
hint: 'Envoyées au franchissement d’un seuil d’alerte d’une base, dans les deux sens : déclenchement et retour à la normale.'
|
|
224
|
+
},
|
|
207
225
|
hasItems: true,
|
|
208
226
|
itemNoun: 'base',
|
|
209
227
|
itemNounGender: 'f',
|
|
@@ -216,6 +234,9 @@ export const FEATURE_REGISTRY: readonly (FeatureDescriptor & { id: WorkspaceFeat
|
|
|
216
234
|
'Lecture : travaux et historique (la liste dit où dorment les copies). Écriture : destinations et déclenchement.',
|
|
217
235
|
icon: 'archive',
|
|
218
236
|
notifies: true,
|
|
237
|
+
notifications: {
|
|
238
|
+
hint: 'Envoyées à l’échec d’une sauvegarde. Les réussites ne disent rien, sinon l’échec se perdrait dans le flot des succès.'
|
|
239
|
+
},
|
|
219
240
|
hasItems: true,
|
|
220
241
|
itemNoun: 'travail',
|
|
221
242
|
sources: {
|
|
@@ -290,8 +311,30 @@ export const FEATURE_REGISTRY: readonly (FeatureDescriptor & { id: WorkspaceFeat
|
|
|
290
311
|
'Lecture : les devises, les unités, et ses propres conversions. Écriture : convertir un fichier, annuler une conversion, retirer un résultat.',
|
|
291
312
|
icon: 'convert',
|
|
292
313
|
notifies: true,
|
|
314
|
+
notifications: {
|
|
315
|
+
hint: 'Envoyées à la fin d’une conversion assez longue pour qu’on ait quitté l’écran. La durée à partir de laquelle prévenir se règle dans l’onglet Général.'
|
|
316
|
+
},
|
|
293
317
|
hasItems: false,
|
|
294
318
|
shareTier: 'never'
|
|
319
|
+
},
|
|
320
|
+
{
|
|
321
|
+
id: 'invoicing',
|
|
322
|
+
label: 'Facturation',
|
|
323
|
+
description:
|
|
324
|
+
'Lecture : les clients, les documents et les règlements. Écriture : tenir le carnet, rédiger un brouillon, enregistrer un règlement.',
|
|
325
|
+
icon: 'invoicing',
|
|
326
|
+
notifies: true,
|
|
327
|
+
notifications: {
|
|
328
|
+
hint: 'Envoyées quand une facture dépasse son échéance sans être soldée, et quand un client accepte ou refuse un devis depuis le lien que vous lui avez envoyé.'
|
|
329
|
+
},
|
|
330
|
+
/**
|
|
331
|
+
* L'élément est le **client**, pas le document : un espace en accumule
|
|
332
|
+
* des centaines, et c'est le client qu'un rôle a une raison de fermer.
|
|
333
|
+
* Un document hérite de la restriction du sien.
|
|
334
|
+
*/
|
|
335
|
+
hasItems: true,
|
|
336
|
+
itemNoun: 'client',
|
|
337
|
+
shareTier: 'never'
|
|
295
338
|
}
|
|
296
339
|
];
|
|
297
340
|
|
|
@@ -336,7 +379,7 @@ export function maybeFeatureDescriptor(id: FeatureId): FeatureDescriptor | undef
|
|
|
336
379
|
return isExternalFeatureId(id) ? EXTERNAL_BY_ID.get(id) : BY_ID.get(id);
|
|
337
380
|
}
|
|
338
381
|
|
|
339
|
-
/** L'intitulé seul
|
|
382
|
+
/** L'intitulé seul : le besoin de très loin le plus courant. */
|
|
340
383
|
export function featureLabel(id: FeatureId): string {
|
|
341
384
|
return featureDescriptor(id).label;
|
|
342
385
|
}
|
package/src/domain/home.ts
CHANGED
package/src/domain/live.ts
CHANGED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Maintenance, site-wide or per feature, set by the global admin (or by the
|
|
5
|
+
* database and the `MAINTENANCE` variable when the interface is out of reach).
|
|
6
|
+
*
|
|
7
|
+
* A feature has two levels: `requests` refuses every non-admin command and
|
|
8
|
+
* public route while its background service keeps running; `full` also stops
|
|
9
|
+
* that service, and refuses admins too, the feature no longer being able to
|
|
10
|
+
* answer.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
export const featureMaintenanceLevelSchema = z.enum(['requests', 'full']);
|
|
14
|
+
export type FeatureMaintenanceLevel = z.infer<typeof featureMaintenanceLevelSchema>;
|
|
15
|
+
|
|
16
|
+
/** What every client of a server knows: enough to eject, grey out and redirect. */
|
|
17
|
+
export const maintenanceStateSchema = z.object({
|
|
18
|
+
site: z.boolean(),
|
|
19
|
+
/** The text shown to everyone the site maintenance keeps out. */
|
|
20
|
+
message: z.string(),
|
|
21
|
+
/** Features under maintenance only; an absent id is open. */
|
|
22
|
+
features: z.record(z.string(), featureMaintenanceLevelSchema)
|
|
23
|
+
});
|
|
24
|
+
export type MaintenanceState = z.infer<typeof maintenanceStateSchema>;
|
|
25
|
+
|
|
26
|
+
/** `GET /api/maintenance`: what an anonymous visitor may learn, without a session. */
|
|
27
|
+
export const publicMaintenanceSchema = maintenanceStateSchema.pick({ site: true, message: true });
|
|
28
|
+
export type PublicMaintenance = z.infer<typeof publicMaintenanceSchema>;
|
|
29
|
+
|
|
30
|
+
/** Server push carrying the whole {@link MaintenanceState}, to every socket, on each change. */
|
|
31
|
+
export const MAINTENANCE_EVENT = 'maintenance.state';
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* WebSocket close code for an account the site maintenance keeps out. The client
|
|
35
|
+
* stops its reconnection backoff: the server refuses again until the end.
|
|
36
|
+
*/
|
|
37
|
+
export const MAINTENANCE_CLOSE_CODE = 4503;
|
|
38
|
+
|
|
39
|
+
/** Upper bound of the site message, on input and in the database. */
|
|
40
|
+
export const MAINTENANCE_MESSAGE_MAX = 1000;
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* The `session` frame that opens every socket. `maintenance` is optional: a
|
|
44
|
+
* remote instance on an older version does not send it.
|
|
45
|
+
*/
|
|
46
|
+
export const sessionFrameSchema = z.object({
|
|
47
|
+
userId: z.number().int().positive(),
|
|
48
|
+
maintenance: maintenanceStateSchema.optional()
|
|
49
|
+
});
|
|
50
|
+
export type SessionFrame = z.infer<typeof sessionFrameSchema>;
|
package/src/domain/sharing.ts
CHANGED
|
@@ -85,7 +85,13 @@ export const itemCopyPlanSchema = z.object({
|
|
|
85
85
|
/** Pourquoi la copie est impossible, en phrases prêtes à afficher. Vide : elle peut partir. */
|
|
86
86
|
blockers: z.array(z.string()),
|
|
87
87
|
/** Ce que la copie n'emportera pas, à énumérer dans la confirmation. */
|
|
88
|
-
drops: z.array(z.string())
|
|
88
|
+
drops: z.array(z.string()),
|
|
89
|
+
/**
|
|
90
|
+
* Ce que la copie emporte et qu'on ne devinerait pas : un secret que la
|
|
91
|
+
* destination pourra lire. Le pendant de `drops`, pour ce qui suit au lieu
|
|
92
|
+
* de rester.
|
|
93
|
+
*/
|
|
94
|
+
carries: z.array(z.string()).default([])
|
|
89
95
|
});
|
|
90
96
|
export type ItemCopyPlan = z.infer<typeof itemCopyPlanSchema>;
|
|
91
97
|
|
|
@@ -146,6 +152,8 @@ export const itemMovePreviewSchema = z.object({
|
|
|
146
152
|
blockers: z.array(z.string()),
|
|
147
153
|
/** Ce qui sera détruit ou retiré, nommé : projections, restrictions, historique. */
|
|
148
154
|
drops: z.array(z.string()),
|
|
155
|
+
/** Ce qui suit l'élément et qu'on ne devinerait pas : un secret lisible à l'arrivée. */
|
|
156
|
+
carries: z.array(z.string()).default([]),
|
|
149
157
|
/** Cellules chiffrées à convertir, pour annoncer l'ampleur plutôt que faire attendre. */
|
|
150
158
|
rows: z.number().int().nonnegative(),
|
|
151
159
|
/** Les liaisons rompues, nommées une par une. */
|
package/src/domain/user.ts
CHANGED
|
@@ -92,8 +92,11 @@ export type UserSecurity = z.infer<typeof userSecuritySchema>;
|
|
|
92
92
|
* - `hideLiveCursors` : ne pas afficher les curseurs des autres membres. La
|
|
93
93
|
* coupure est réciproque : le client cesse aussi d'émettre le sien, on ne
|
|
94
94
|
* peut pas regarder sans être vu.
|
|
95
|
+
* - `feedbackHintDismissed` : la bulle qui présente le bouton de signalement a
|
|
96
|
+
* été vue. Posée par sa croix comme par l'ouverture du formulaire, elle ne
|
|
97
|
+
* se retire jamais : la bulle se montre une fois dans la vie d'un compte.
|
|
95
98
|
*/
|
|
96
|
-
export const userSettingFlagSchema = z.enum(['hideLiveCursors']);
|
|
99
|
+
export const userSettingFlagSchema = z.enum(['hideLiveCursors', 'feedbackHintDismissed']);
|
|
97
100
|
export type UserSettingFlag = z.infer<typeof userSettingFlagSchema>;
|
|
98
101
|
|
|
99
102
|
export const userSchema = z.object({
|
|
@@ -101,7 +101,14 @@ export const workspaceFeatureIdSchema = z.enum([
|
|
|
101
101
|
* conversions ; `write` = convertir un fichier, annuler, retirer. Personne
|
|
102
102
|
* ne voit les conversions d'un autre membre.
|
|
103
103
|
*/
|
|
104
|
-
'convert'
|
|
104
|
+
'convert',
|
|
105
|
+
/**
|
|
106
|
+
* Facturation. `read` = consulter les clients, les devis, les factures et
|
|
107
|
+
* les règlements. `write` = tenir le carnet, rédiger et corriger un
|
|
108
|
+
* brouillon, enregistrer un règlement. Émettre un document et changer
|
|
109
|
+
* l'identité de l'émetteur sont des permissions propres du module.
|
|
110
|
+
*/
|
|
111
|
+
'invoicing'
|
|
105
112
|
]);
|
|
106
113
|
|
|
107
114
|
export type WorkspaceFeatureId = z.infer<typeof workspaceFeatureIdSchema>;
|
package/src/features/admin.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
|
+
import { featureMaintenanceLevelSchema, MAINTENANCE_MESSAGE_MAX } from '../domain/maintenance';
|
|
2
3
|
import { userRoleSchema } from '../domain/role';
|
|
3
4
|
import { userStatusSchema } from '../domain/user';
|
|
4
5
|
|
|
@@ -54,9 +55,77 @@ export const adminDeleteUser = {
|
|
|
54
55
|
output: z.object({ userId: z.number().int().positive() })
|
|
55
56
|
};
|
|
56
57
|
|
|
58
|
+
/** Qui a fait le dernier changement, `null` depuis la base ou si le compte a disparu. */
|
|
59
|
+
const maintenanceAuthorSchema = z
|
|
60
|
+
.object({ id: z.number().int().positive(), username: z.string() })
|
|
61
|
+
.nullable();
|
|
62
|
+
|
|
63
|
+
export const adminMaintenanceSchema = z.object({
|
|
64
|
+
site: z.object({
|
|
65
|
+
active: z.boolean(),
|
|
66
|
+
/** Le texte choisi, `null` pour celui par défaut. */
|
|
67
|
+
message: z.string().nullable(),
|
|
68
|
+
defaultMessage: z.string(),
|
|
69
|
+
/** Le processus a démarré avec `MAINTENANCE=1`. */
|
|
70
|
+
envSeeded: z.boolean(),
|
|
71
|
+
updated: z.number().int().nonnegative(),
|
|
72
|
+
updatedBy: maintenanceAuthorSchema
|
|
73
|
+
}),
|
|
74
|
+
/** Chaque module installé, ouvert ou non. */
|
|
75
|
+
features: z.array(
|
|
76
|
+
z.object({
|
|
77
|
+
id: z.string(),
|
|
78
|
+
level: featureMaintenanceLevelSchema.nullable(),
|
|
79
|
+
/** Sans service de fond, l'arrêt complet n'a rien à arrêter. */
|
|
80
|
+
hasService: z.boolean(),
|
|
81
|
+
updated: z.number().int().nonnegative().nullable(),
|
|
82
|
+
updatedBy: maintenanceAuthorSchema
|
|
83
|
+
})
|
|
84
|
+
)
|
|
85
|
+
});
|
|
86
|
+
|
|
87
|
+
export type AdminMaintenance = z.infer<typeof adminMaintenanceSchema>;
|
|
88
|
+
|
|
89
|
+
export const adminMaintenanceGet = {
|
|
90
|
+
command: 'admin.maintenanceGet' as const,
|
|
91
|
+
input: z.object({}),
|
|
92
|
+
output: adminMaintenanceSchema
|
|
93
|
+
};
|
|
94
|
+
|
|
95
|
+
/** Mettre le site en maintenance déconnecte sur-le-champ tout compte non administrateur. */
|
|
96
|
+
export const adminMaintenanceSite = {
|
|
97
|
+
command: 'admin.maintenanceSite' as const,
|
|
98
|
+
input: z.object({
|
|
99
|
+
active: z.boolean(),
|
|
100
|
+
message: z.string().trim().min(1).max(MAINTENANCE_MESSAGE_MAX).nullable()
|
|
101
|
+
}),
|
|
102
|
+
output: adminMaintenanceSchema
|
|
103
|
+
};
|
|
104
|
+
|
|
105
|
+
/** `level: null` rouvre la feature. */
|
|
106
|
+
export const adminMaintenanceFeature = {
|
|
107
|
+
command: 'admin.maintenanceFeature' as const,
|
|
108
|
+
input: z.object({
|
|
109
|
+
feature: z.string().min(1).max(64),
|
|
110
|
+
level: featureMaintenanceLevelSchema.nullable()
|
|
111
|
+
}),
|
|
112
|
+
output: adminMaintenanceSchema
|
|
113
|
+
};
|
|
114
|
+
|
|
115
|
+
/** Ferme le rappel de `MAINTENANCE=1`, pour tous les administrateurs. */
|
|
116
|
+
export const adminMaintenanceDismissNotice = {
|
|
117
|
+
command: 'admin.maintenanceDismissNotice' as const,
|
|
118
|
+
input: z.object({}),
|
|
119
|
+
output: z.object({})
|
|
120
|
+
};
|
|
121
|
+
|
|
57
122
|
export const adminCommands = [
|
|
58
123
|
adminUserList,
|
|
59
124
|
adminSetUserRole,
|
|
60
125
|
adminSetUserStatus,
|
|
61
|
-
adminDeleteUser
|
|
126
|
+
adminDeleteUser,
|
|
127
|
+
adminMaintenanceGet,
|
|
128
|
+
adminMaintenanceSite,
|
|
129
|
+
adminMaintenanceFeature,
|
|
130
|
+
adminMaintenanceDismissNotice
|
|
62
131
|
] as const;
|
package/src/features/domain.ts
CHANGED
|
@@ -12,7 +12,22 @@ import { featureIdSchema } from '../domain/workspaceRole';
|
|
|
12
12
|
export const domainList = {
|
|
13
13
|
command: 'domain.list' as const,
|
|
14
14
|
input: z.object({ feature: featureIdSchema }),
|
|
15
|
-
output: z.object({
|
|
15
|
+
output: z.object({
|
|
16
|
+
domains: z.array(featureDomainSchema),
|
|
17
|
+
/**
|
|
18
|
+
* How a web domain gets its HTTPS certificate on this instance: `auto`
|
|
19
|
+
* when DevEye feeds its proxy, `manual` when the administrator adds
|
|
20
|
+
* each name. Null when the feature's domains are not web ones.
|
|
21
|
+
*/
|
|
22
|
+
https: z.enum(['auto', 'manual']).nullable(),
|
|
23
|
+
/**
|
|
24
|
+
* The workspace owner's allowance of web domains, counted as distinct
|
|
25
|
+
* names across all their workspaces. Null when unbounded.
|
|
26
|
+
*/
|
|
27
|
+
quota: z
|
|
28
|
+
.object({ used: z.number().int().nonnegative(), limit: z.number().int().nonnegative() })
|
|
29
|
+
.nullable()
|
|
30
|
+
})
|
|
16
31
|
};
|
|
17
32
|
|
|
18
33
|
export const domainAdd = {
|
package/src/http/auth.ts
CHANGED
|
@@ -29,7 +29,13 @@ export const sessionBundleSchema = z.object({
|
|
|
29
29
|
* le bundle plutôt que par une requête à part : le client doit le savoir
|
|
30
30
|
* avant son premier rendu, pour ne pas faire clignoter le bouton.
|
|
31
31
|
*/
|
|
32
|
-
feedbackEnabled: z.boolean()
|
|
32
|
+
feedbackEnabled: z.boolean(),
|
|
33
|
+
/**
|
|
34
|
+
* Admin only: the process booted with `MAINTENANCE=1` and no admin has
|
|
35
|
+
* closed the reminder. Shown once the site maintenance is lifted. Read at
|
|
36
|
+
* load, not live.
|
|
37
|
+
*/
|
|
38
|
+
maintenanceEnvNotice: z.boolean()
|
|
33
39
|
});
|
|
34
40
|
|
|
35
41
|
export type SessionBundle = z.infer<typeof sessionBundleSchema>;
|
package/src/index.ts
CHANGED
|
@@ -293,6 +293,21 @@ export type {
|
|
|
293
293
|
FeedbackStatus,
|
|
294
294
|
FeedbackViewTrace
|
|
295
295
|
} from './domain/feedback';
|
|
296
|
+
export {
|
|
297
|
+
featureMaintenanceLevelSchema,
|
|
298
|
+
MAINTENANCE_CLOSE_CODE,
|
|
299
|
+
MAINTENANCE_EVENT,
|
|
300
|
+
MAINTENANCE_MESSAGE_MAX,
|
|
301
|
+
maintenanceStateSchema,
|
|
302
|
+
publicMaintenanceSchema,
|
|
303
|
+
sessionFrameSchema
|
|
304
|
+
} from './domain/maintenance';
|
|
305
|
+
export type {
|
|
306
|
+
FeatureMaintenanceLevel,
|
|
307
|
+
MaintenanceState,
|
|
308
|
+
PublicMaintenance,
|
|
309
|
+
SessionFrame
|
|
310
|
+
} from './domain/maintenance';
|
|
296
311
|
export {
|
|
297
312
|
DEVICE_LOG_LEVELS,
|
|
298
313
|
DEVICE_LOG_OFFSET_MAX,
|
|
@@ -782,12 +797,17 @@ export type {
|
|
|
782
797
|
export {
|
|
783
798
|
adminCommands,
|
|
784
799
|
adminDeleteUser,
|
|
800
|
+
adminMaintenanceDismissNotice,
|
|
801
|
+
adminMaintenanceFeature,
|
|
802
|
+
adminMaintenanceGet,
|
|
803
|
+
adminMaintenanceSchema,
|
|
804
|
+
adminMaintenanceSite,
|
|
785
805
|
adminSetUserRole,
|
|
786
806
|
adminSetUserStatus,
|
|
787
807
|
adminUserList,
|
|
788
808
|
adminUserSchema
|
|
789
809
|
} from './features/admin';
|
|
790
|
-
export type { AdminUser } from './features/admin';
|
|
810
|
+
export type { AdminMaintenance, AdminUser } from './features/admin';
|
|
791
811
|
export {
|
|
792
812
|
workspaceActivate,
|
|
793
813
|
workspaceAdd,
|
package/src/protocol/error.ts
CHANGED
|
@@ -16,7 +16,10 @@ export const ErrorCodeSchema = z.enum([
|
|
|
16
16
|
'unsupported_version',
|
|
17
17
|
// Password-based encryption is enabled but the session has not yet been
|
|
18
18
|
// unlocked with the user's password. The client should prompt for it.
|
|
19
|
-
'locked'
|
|
19
|
+
'locked',
|
|
20
|
+
// The site, or the feature the command belongs to, is under maintenance
|
|
21
|
+
// (see `domain/maintenance.ts`). The message is the one to show.
|
|
22
|
+
'maintenance'
|
|
20
23
|
]);
|
|
21
24
|
|
|
22
25
|
export type ErrorCode = z.infer<typeof ErrorCodeSchema>;
|
|
@@ -182,9 +182,15 @@ declare module 'deveye-sdk-client' {
|
|
|
182
182
|
*/
|
|
183
183
|
export const CountBadge: ComponentType<CountBadgeProps>;
|
|
184
184
|
/**
|
|
185
|
-
*
|
|
186
|
-
*
|
|
187
|
-
*
|
|
185
|
+
* The save button of a settings panel: "Saving…" during the round trip,
|
|
186
|
+
* "Saved" for a few seconds, then its label again. Errors stay in the panel;
|
|
187
|
+
* they do not clear on their own.
|
|
188
|
+
*
|
|
189
|
+
* Its place follows what it saves. `placement: 'footer'` (default) pins it
|
|
190
|
+
* to the bottom right of the settings dialog, outside what scrolls: for a
|
|
191
|
+
* button that saves the whole tab. `'inline'` leaves it where it is written:
|
|
192
|
+
* for a button that saves one block or one entry of a list. Outside a
|
|
193
|
+
* settings dialog, both render inline.
|
|
188
194
|
*/
|
|
189
195
|
export const SaveButton: ComponentType<{
|
|
190
196
|
onSave: () => Promise<unknown> | unknown;
|
|
@@ -193,6 +199,7 @@ declare module 'deveye-sdk-client' {
|
|
|
193
199
|
variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
|
|
194
200
|
icon?: string;
|
|
195
201
|
title?: string;
|
|
202
|
+
placement?: 'footer' | 'inline';
|
|
196
203
|
}>;
|
|
197
204
|
export const Dialog: ComponentType<{
|
|
198
205
|
open: boolean;
|
|
@@ -283,6 +290,20 @@ declare module 'deveye-sdk-client' {
|
|
|
283
290
|
onClose: () => void;
|
|
284
291
|
busy?: boolean;
|
|
285
292
|
}>;
|
|
293
|
+
/**
|
|
294
|
+
* Points at the settings button of `scope` for about a second: the gesture
|
|
295
|
+
* that follows an action taken OUTSIDE the settings (a banner that puts a
|
|
296
|
+
* page back online), so the user learns where that setting lives. Only the
|
|
297
|
+
* canonical button answers, the one mounted without `initialSection`:
|
|
298
|
+
* shortcuts to a given tab share the scope and would all light up. Does
|
|
299
|
+
* nothing when no such button is on screen. Honors `prefers-reduced-motion`
|
|
300
|
+
* with a still outline.
|
|
301
|
+
*/
|
|
302
|
+
export function flashSettings(
|
|
303
|
+
scope:
|
|
304
|
+
| { kind: 'feature'; feature: FeatureId }
|
|
305
|
+
| { kind: 'item'; feature: FeatureId; itemId: string }
|
|
306
|
+
): void;
|
|
286
307
|
export const FeatureSettingsButton: ComponentType<{
|
|
287
308
|
scope:
|
|
288
309
|
| { kind: 'feature'; feature: FeatureId }
|
|
@@ -293,7 +314,12 @@ declare module 'deveye-sdk-client' {
|
|
|
293
314
|
itemLabel: string;
|
|
294
315
|
shareable?: boolean;
|
|
295
316
|
};
|
|
296
|
-
|
|
317
|
+
/**
|
|
318
|
+
* `link` renders an underlined word instead of a button, for the gesture
|
|
319
|
+
* dropped into a sentence or into a cell too narrow for a button: same
|
|
320
|
+
* door, same dialog, another skin.
|
|
321
|
+
*/
|
|
322
|
+
variant?: 'primary' | 'secondary' | 'danger' | 'ghost' | 'link';
|
|
297
323
|
label?: string;
|
|
298
324
|
/** The tab a click opens (one of the manifest's tab ids); the first by default. */
|
|
299
325
|
initialSection?: string;
|
|
@@ -348,6 +374,22 @@ declare module 'deveye-sdk-client' {
|
|
|
348
374
|
* cannot be projected) keeps its own wording.
|
|
349
375
|
*/
|
|
350
376
|
export const ReadOnlyNotice: ComponentType<{ children: ReactNode }>;
|
|
377
|
+
export interface ErrorNoteInput {
|
|
378
|
+
message: string;
|
|
379
|
+
code: string | null;
|
|
380
|
+
}
|
|
381
|
+
export interface ErrorNoteProps {
|
|
382
|
+
note: ErrorNoteInput | null;
|
|
383
|
+
children?: ReactNode;
|
|
384
|
+
}
|
|
385
|
+
/**
|
|
386
|
+
* A refusal banner: the sentence, the caller's own repair actions as
|
|
387
|
+
* children, and a report button when the failure is not one the user can
|
|
388
|
+
* fix on their own.
|
|
389
|
+
*/
|
|
390
|
+
export const ErrorNote: ComponentType<ErrorNoteProps>;
|
|
391
|
+
/** Open the report form, primed with what failed. */
|
|
392
|
+
export function openReport(context?: string | null): void;
|
|
351
393
|
/** The canonical settings row classes (channelRow, field, sectionHint...). */
|
|
352
394
|
export const settingsStyles: Readonly<Record<string, string>>;
|
|
353
395
|
/** A plain count on a home card: a big number, a noun, a secondary line. */
|
package/src/sdk/manifest.test.ts
CHANGED
|
@@ -45,18 +45,21 @@ test('externalDescriptorOf projects the identity fields only, and refuses a nati
|
|
|
45
45
|
...base,
|
|
46
46
|
itemNoun: 'thing',
|
|
47
47
|
itemNounGender: 'f',
|
|
48
|
-
sources: { hint: 'keys' }
|
|
48
|
+
sources: { hint: 'keys' },
|
|
49
|
+
notifies: true,
|
|
50
|
+
notifications: { hint: 'on every booking' }
|
|
49
51
|
}),
|
|
50
52
|
{
|
|
51
53
|
id: 'x-demo',
|
|
52
54
|
label: 'Demo',
|
|
53
55
|
description: 'A demo module.',
|
|
54
56
|
icon: 'x-demo-icon',
|
|
55
|
-
notifies:
|
|
57
|
+
notifies: true,
|
|
56
58
|
hasItems: false,
|
|
57
59
|
itemNoun: 'thing',
|
|
58
60
|
itemNounGender: 'f',
|
|
59
61
|
sources: { hint: 'keys' },
|
|
62
|
+
notifications: { hint: 'on every booking' },
|
|
60
63
|
shareTier: 'never'
|
|
61
64
|
}
|
|
62
65
|
);
|
|
@@ -160,3 +163,21 @@ test('validateManifest checks quotas and the account entry', () => {
|
|
|
160
163
|
rejects({ accountOnly: true, accountEntry: { label: 'S' }, tile: {} }, 'no tile');
|
|
161
164
|
rejects({ accountEntry: { label: ' ' } }, 'requires a label');
|
|
162
165
|
});
|
|
166
|
+
|
|
167
|
+
test('a notifying manifest says when it notifies, and only then', () => {
|
|
168
|
+
const rejects = (patch: Partial<FeatureManifest>, fragment: string) =>
|
|
169
|
+
assert.throws(() => validateManifest({ ...base, ...patch }), new RegExp(fragment));
|
|
170
|
+
assert.doesNotThrow(() =>
|
|
171
|
+
validateManifest({
|
|
172
|
+
...base,
|
|
173
|
+
notifies: true,
|
|
174
|
+
notifications: { hint: 'Sent when a booking is made.' }
|
|
175
|
+
})
|
|
176
|
+
);
|
|
177
|
+
rejects({ notifies: true }, 'notifies requires notifications.hint');
|
|
178
|
+
rejects(
|
|
179
|
+
{ notifies: true, notifications: { hint: ' ' } },
|
|
180
|
+
'notifies requires notifications.hint'
|
|
181
|
+
);
|
|
182
|
+
rejects({ notifications: { hint: 'Sent when…' } }, 'without notifies');
|
|
183
|
+
});
|
package/src/sdk/manifest.ts
CHANGED
|
@@ -237,6 +237,12 @@ export interface FeatureManifest<Id extends FeatureId = FeatureId> {
|
|
|
237
237
|
itemNounGender?: 'm' | 'f';
|
|
238
238
|
/** Feature-scope reusable settings (API keys, destinations). Opens the Sources tab. */
|
|
239
239
|
sources?: { hint: string };
|
|
240
|
+
/**
|
|
241
|
+
* WHEN the feature notifies, as the lead sentence of its Notifications tab.
|
|
242
|
+
* Required with `notifies`: a tab that lists channels without saying what
|
|
243
|
+
* reaches them leaves the user guessing why they would set one up.
|
|
244
|
+
*/
|
|
245
|
+
notifications?: { hint: string };
|
|
240
246
|
/**
|
|
241
247
|
* The feature serves something under domain names the workspace owns (a
|
|
242
248
|
* public page, a mailbox). Opens the Domains tab, which DevEye renders:
|
|
@@ -252,6 +258,14 @@ export interface FeatureManifest<Id extends FeatureId = FeatureId> {
|
|
|
252
258
|
placeholder?: string;
|
|
253
259
|
/** Warning of the removal confirm when items designate the domain. */
|
|
254
260
|
removal?: string;
|
|
261
|
+
/**
|
|
262
|
+
* The names serve your public routes over HTTPS (a CNAME to
|
|
263
|
+
* `origins.public`). DevEye then checks by itself that a name points
|
|
264
|
+
* here and answers in HTTPS before calling your probe, hands it to its
|
|
265
|
+
* proxy for a certificate when the instance is wired for it, and
|
|
266
|
+
* counts it against the `domains.hosts` plan limit.
|
|
267
|
+
*/
|
|
268
|
+
web?: boolean;
|
|
255
269
|
};
|
|
256
270
|
/**
|
|
257
271
|
* Whether an item can be projected into another workspace. Decided by
|
|
@@ -474,6 +488,11 @@ export function validateManifest(m: FeatureManifest): void {
|
|
|
474
488
|
}
|
|
475
489
|
}
|
|
476
490
|
|
|
491
|
+
if (m.notifies && !m.notifications?.hint.trim()) {
|
|
492
|
+
fail(m.id, 'notifies requires notifications.hint: say when the feature notifies');
|
|
493
|
+
}
|
|
494
|
+
if (m.notifications && !m.notifies) fail(m.id, 'notifications.hint without notifies');
|
|
495
|
+
|
|
477
496
|
if (m.domains) {
|
|
478
497
|
if (!m.domains.hint.trim()) fail(m.id, 'domains: empty hint');
|
|
479
498
|
if (!m.domains.service.trim()) fail(m.id, 'domains: empty service');
|
|
@@ -533,6 +552,7 @@ export function externalDescriptorOf(
|
|
|
533
552
|
itemNoun: m.itemNoun,
|
|
534
553
|
itemNounGender: m.itemNounGender,
|
|
535
554
|
sources: m.sources,
|
|
555
|
+
notifications: m.notifications,
|
|
536
556
|
shareTier: m.shareTier
|
|
537
557
|
};
|
|
538
558
|
}
|
package/src/sdk/server.ts
CHANGED
|
@@ -786,8 +786,10 @@ export interface SdkFeatureContext<Repo = unknown> {
|
|
|
786
786
|
live: SdkContextLive;
|
|
787
787
|
/**
|
|
788
788
|
* Where DevEye lives, as URLs without a trailing slash: `app` is the
|
|
789
|
-
* origin members use (`PUBLIC_ORIGIN`), `public` the one
|
|
790
|
-
*
|
|
789
|
+
* origin members use (`PUBLIC_ORIGIN`), `public` the one anyone reaches
|
|
790
|
+
* the public routes by, which differs when the host serves them on a
|
|
791
|
+
* domain of their own, the app itself possibly staying private (else the
|
|
792
|
+
* same).
|
|
791
793
|
* For what a module hands to the outside world (an install snippet, a
|
|
792
794
|
* callback URL): never derive it from the browser's location.
|
|
793
795
|
*/
|
|
@@ -895,6 +897,13 @@ export interface SdkPublicRouteOptions {
|
|
|
895
897
|
exposure?: 'everywhere' | 'app';
|
|
896
898
|
/** Also hand the handler the undecoded body (`SdkPublicRequest.rawBody`). JSON bodies only. */
|
|
897
899
|
rawBody?: boolean;
|
|
900
|
+
/**
|
|
901
|
+
* Largest body this route accepts, in bytes. Size it on the biggest
|
|
902
|
+
* legitimate call: the host default is a megabyte, which is orders of
|
|
903
|
+
* magnitude above what a beacon or a form sends, and every byte of it is
|
|
904
|
+
* parsed before your schema sees anything.
|
|
905
|
+
*/
|
|
906
|
+
bodyLimit?: number;
|
|
898
907
|
}
|
|
899
908
|
|
|
900
909
|
/** What a redeemed ticket gives a public route back (see `SdkSecrecy.ticket`). */
|
|
@@ -962,7 +971,10 @@ export interface SdkPublicApp {
|
|
|
962
971
|
|
|
963
972
|
/**
|
|
964
973
|
* A background worker. Started during boot (awaited, before the agent socket
|
|
965
|
-
* layer registers), stopped on shutdown.
|
|
974
|
+
* layer registers), stopped on shutdown. A full-stop maintenance of the feature
|
|
975
|
+
* also stops it at runtime, then calls `start()` again on the same object: stop
|
|
976
|
+
* must resolve once the work in flight is finished or interrupted, and leave
|
|
977
|
+
* nothing that would break a second start. Stopping a stopped service is a no-op.
|
|
966
978
|
*/
|
|
967
979
|
export interface FeatureService {
|
|
968
980
|
start(): void | Promise<void>;
|
|
@@ -1038,6 +1050,7 @@ export interface FeatureServiceDeps<Repo = unknown> {
|
|
|
1038
1050
|
/**
|
|
1039
1051
|
* The app's standard loop: setInterval + reentrancy guard + unref, the
|
|
1040
1052
|
* exact pattern of every native service. Use it instead of rolling your own.
|
|
1053
|
+
* `stop()` resolves once the tick in flight, if any, has finished: await it.
|
|
1041
1054
|
*/
|
|
1042
1055
|
createTicker(opts: { intervalMs: number; tick(): Promise<void> }): FeatureService;
|
|
1043
1056
|
logger: SdkLogger;
|
|
@@ -1129,6 +1142,13 @@ export interface SdkCopyPlan {
|
|
|
1129
1142
|
* token of the origin workspace, a history the destination rebuilds.
|
|
1130
1143
|
*/
|
|
1131
1144
|
drops: readonly string[];
|
|
1145
|
+
/**
|
|
1146
|
+
* What the copy DOES carry and nobody would guess: a secret the destination
|
|
1147
|
+
* will be able to read, such as a password the item authenticates with.
|
|
1148
|
+
* Optional, because most items have nothing to declare here; say it and the
|
|
1149
|
+
* confirmation lists it, or whoever copies never learns it.
|
|
1150
|
+
*/
|
|
1151
|
+
carries?: readonly string[];
|
|
1132
1152
|
}
|
|
1133
1153
|
|
|
1134
1154
|
/** See {@link FeatureItemsEntry.copy}. */
|
|
@@ -1199,6 +1219,12 @@ export interface SdkMovePlan {
|
|
|
1199
1219
|
* Say it here or the caller discovers it afterwards.
|
|
1200
1220
|
*/
|
|
1201
1221
|
drops: readonly string[];
|
|
1222
|
+
/**
|
|
1223
|
+
* What follows the item and nobody would guess: a secret the destination
|
|
1224
|
+
* workspace will be able to read. Optional, same contract as
|
|
1225
|
+
* {@link SdkCopyPlan.carries}.
|
|
1226
|
+
*/
|
|
1227
|
+
carries?: readonly string[];
|
|
1202
1228
|
/**
|
|
1203
1229
|
* Encrypted cells to convert, so the confirmation can say how much rather
|
|
1204
1230
|
* than spin. An estimate is fine; zero is a legitimate answer.
|