@deveye/types 0.19.1 → 0.20.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +6 -0
- package/package.json +1 -1
- package/src/domain/featureRegistry.test.ts +33 -0
- package/src/domain/featureRegistry.ts +55 -2
- package/src/domain/home.ts +3 -1
- package/src/domain/live.ts +2 -0
- package/src/domain/maintenance.ts +50 -0
- package/src/domain/notifications.ts +3 -1
- package/src/domain/sharing.ts +9 -1
- package/src/domain/user.ts +4 -1
- package/src/domain/workspaceRole.ts +14 -1
- package/src/features/admin.ts +70 -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 +143 -5
- package/src/sdk/manifest.test.ts +23 -2
- package/src/sdk/manifest.ts +15 -2
- package/src/sdk/server.ts +74 -1
- package/src/sdk/testing.test.ts +22 -0
- package/src/sdk/testing.ts +21 -1
package/README.md
CHANGED
|
@@ -21,3 +21,9 @@ DevEye vérifie mécaniquement que le vrai barrel l'honore.
|
|
|
21
21
|
|
|
22
22
|
Pour écrire un module : partir du
|
|
23
23
|
[template](https://github.com/Gerem66/DevEye-Feature-Template) et sa doc.
|
|
24
|
+
|
|
25
|
+
## Licence
|
|
26
|
+
|
|
27
|
+
[MIT](LICENSE). Un module bâti sur ce paquet se licencie comme son auteur
|
|
28
|
+
l'entend : le cœur de DevEye est sous AGPL-3.0, avec une exception pour ce qui
|
|
29
|
+
ne passe que par ce SDK (`LICENSING.md` du dépôt de l'app).
|
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: {
|
|
@@ -282,6 +303,38 @@ export const FEATURE_REGISTRY: readonly (FeatureDescriptor & { id: WorkspaceFeat
|
|
|
282
303
|
itemNoun: 'adresse',
|
|
283
304
|
itemNounGender: 'f',
|
|
284
305
|
shareTier: 'open'
|
|
306
|
+
},
|
|
307
|
+
{
|
|
308
|
+
id: 'convert',
|
|
309
|
+
label: 'Convertisseur',
|
|
310
|
+
description:
|
|
311
|
+
'Lecture : les devises, les unités, et ses propres conversions. Écriture : convertir un fichier, annuler une conversion, retirer un résultat.',
|
|
312
|
+
icon: 'convert',
|
|
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
|
+
},
|
|
317
|
+
hasItems: false,
|
|
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'
|
|
285
338
|
}
|
|
286
339
|
];
|
|
287
340
|
|
|
@@ -326,7 +379,7 @@ export function maybeFeatureDescriptor(id: FeatureId): FeatureDescriptor | undef
|
|
|
326
379
|
return isExternalFeatureId(id) ? EXTERNAL_BY_ID.get(id) : BY_ID.get(id);
|
|
327
380
|
}
|
|
328
381
|
|
|
329
|
-
/** L'intitulé seul
|
|
382
|
+
/** L'intitulé seul : le besoin de très loin le plus courant. */
|
|
330
383
|
export function featureLabel(id: FeatureId): string {
|
|
331
384
|
return featureDescriptor(id).label;
|
|
332
385
|
}
|
package/src/domain/home.ts
CHANGED
package/src/domain/live.ts
CHANGED
|
@@ -200,6 +200,8 @@ export const TOPIC_FEATURE: Record<NativeLiveTopic, WorkspaceFeatureId | null> =
|
|
|
200
200
|
osint: 'osint',
|
|
201
201
|
cve: 'cve',
|
|
202
202
|
mailserver: 'mailserver',
|
|
203
|
+
convert: 'convert',
|
|
204
|
+
invoicing: 'invoicing',
|
|
203
205
|
workspace: null,
|
|
204
206
|
home: null,
|
|
205
207
|
account: null,
|
|
@@ -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({
|
|
@@ -95,7 +95,20 @@ export const workspaceFeatureIdSchema = z.enum([
|
|
|
95
95
|
* Réinitialiser un mot de passe et purger la file d'envoi sont des
|
|
96
96
|
* permissions propres du module.
|
|
97
97
|
*/
|
|
98
|
-
'mailserver'
|
|
98
|
+
'mailserver',
|
|
99
|
+
/**
|
|
100
|
+
* Convertisseur. `read` = les devises, les unités, et ses propres
|
|
101
|
+
* conversions ; `write` = convertir un fichier, annuler, retirer. Personne
|
|
102
|
+
* ne voit les conversions d'un autre membre.
|
|
103
|
+
*/
|
|
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'
|
|
99
112
|
]);
|
|
100
113
|
|
|
101
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/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>;
|
|
@@ -63,9 +63,76 @@ declare module 'deveye-sdk-client' {
|
|
|
63
63
|
disabled?: boolean;
|
|
64
64
|
'aria-label'?: string;
|
|
65
65
|
}>;
|
|
66
|
+
/**
|
|
67
|
+
* The app's number field: a native number input between two ± buttons.
|
|
68
|
+
* `null` is an empty field. What is being typed is never rewritten while
|
|
69
|
+
* the field has focus; the value is clamped to `min`/`max` on blur. `live`
|
|
70
|
+
* reports every in-range keystroke, for what shows at once (a preview).
|
|
71
|
+
* On the focused field only, the wheel steps by `step`, by fifty steps with
|
|
72
|
+
* Ctrl or Shift held; anywhere else it scrolls the page.
|
|
73
|
+
*/
|
|
74
|
+
export const NumberInput: ComponentType<{
|
|
75
|
+
value: number | null;
|
|
76
|
+
onChange: (value: number | null) => void;
|
|
77
|
+
min?: number;
|
|
78
|
+
max?: number;
|
|
79
|
+
step?: number;
|
|
80
|
+
placeholder?: string;
|
|
81
|
+
disabled?: boolean;
|
|
82
|
+
live?: boolean;
|
|
83
|
+
/** For a wrapping `<label htmlFor>`: without it, clicking the label would press "−". */
|
|
84
|
+
id?: string;
|
|
85
|
+
'aria-label'?: string;
|
|
86
|
+
className?: string;
|
|
87
|
+
}>;
|
|
88
|
+
/** One choice of a `SearchSelect`. `prefix` is decorative (a flag, an avatar); `keywords` widen what the search reads. */
|
|
89
|
+
export interface SearchSelectOption<T extends string = string> {
|
|
90
|
+
value: T;
|
|
91
|
+
label: string;
|
|
92
|
+
prefix?: ReactNode;
|
|
93
|
+
detail?: string;
|
|
94
|
+
keywords?: readonly string[];
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* A dropdown one can search in (accent- and case-insensitive), for a list too
|
|
98
|
+
* long to scan: currencies, units, countries. Under ten choices or so,
|
|
99
|
+
* `SelectInput` stays simpler. Safe inside a Dialog: the panel is portaled.
|
|
100
|
+
*/
|
|
101
|
+
export function SearchSelect<T extends string>(props: {
|
|
102
|
+
value: T;
|
|
103
|
+
options: readonly SearchSelectOption<T>[];
|
|
104
|
+
onChange: (value: T) => void;
|
|
105
|
+
'aria-label': string;
|
|
106
|
+
/** What the trigger shows when no option carries the current value. */
|
|
107
|
+
placeholder?: string;
|
|
108
|
+
searchPlaceholder?: string;
|
|
109
|
+
emptyText?: string;
|
|
110
|
+
disabled?: boolean;
|
|
111
|
+
className?: string;
|
|
112
|
+
}): ReactNode;
|
|
113
|
+
/**
|
|
114
|
+
* A labelled range input. `valueLabel` is how the value reads ("24", "80 %");
|
|
115
|
+
* `marks` sit under the track; `indicator` draws a discreet tick at a
|
|
116
|
+
* reference value (decorative: say what it means in `hint`).
|
|
117
|
+
*/
|
|
118
|
+
export const Slider: ComponentType<{
|
|
119
|
+
value: number;
|
|
120
|
+
onChange: (value: number) => void;
|
|
121
|
+
min: number;
|
|
122
|
+
max: number;
|
|
123
|
+
step?: number;
|
|
124
|
+
label: string;
|
|
125
|
+
valueLabel?: string;
|
|
126
|
+
marks?: readonly string[];
|
|
127
|
+
indicator?: number;
|
|
128
|
+
hint?: string;
|
|
129
|
+
disabled?: boolean;
|
|
130
|
+
className?: string;
|
|
131
|
+
}>;
|
|
66
132
|
export function SegmentedControl<T extends string>(props: {
|
|
67
133
|
value: T;
|
|
68
|
-
|
|
134
|
+
/** `detail`: a small line under the label, what the choice amounts to here ("Original", then "30 fps"). */
|
|
135
|
+
options: readonly { value: T; label: string; title?: string; detail?: string }[];
|
|
69
136
|
onChange: (value: T) => void;
|
|
70
137
|
/** Étire le groupe sur la ligne, chaque choix en prenant une part égale. */
|
|
71
138
|
fullWidth?: boolean;
|
|
@@ -98,10 +165,32 @@ declare module 'deveye-sdk-client' {
|
|
|
98
165
|
onPick?: (value: T) => void;
|
|
99
166
|
'aria-label'?: string;
|
|
100
167
|
}): ReactNode;
|
|
168
|
+
/** One choice of a `CountBadge`: what it counts, and whether it asks to be seen. */
|
|
169
|
+
export interface CountBadgeProps {
|
|
170
|
+
count: number;
|
|
171
|
+
/** `accent` (default): unread, something to act on. `neutral`: a plain count. */
|
|
172
|
+
tone?: 'accent' | 'neutral';
|
|
173
|
+
/** Above it, the badge reads "99+". Default 99. */
|
|
174
|
+
max?: number;
|
|
175
|
+
/** Needed when the number alone does not say what it counts. */
|
|
176
|
+
'aria-label'?: string;
|
|
177
|
+
className?: string;
|
|
178
|
+
}
|
|
101
179
|
/**
|
|
102
|
-
*
|
|
103
|
-
*
|
|
104
|
-
|
|
180
|
+
* A counter pill: a number in a round. Round on one digit, a capsule beyond,
|
|
181
|
+
* its content centred both ways, which plain padding does not give.
|
|
182
|
+
*/
|
|
183
|
+
export const CountBadge: ComponentType<CountBadgeProps>;
|
|
184
|
+
/**
|
|
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.
|
|
105
194
|
*/
|
|
106
195
|
export const SaveButton: ComponentType<{
|
|
107
196
|
onSave: () => Promise<unknown> | unknown;
|
|
@@ -110,6 +199,7 @@ declare module 'deveye-sdk-client' {
|
|
|
110
199
|
variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
|
|
111
200
|
icon?: string;
|
|
112
201
|
title?: string;
|
|
202
|
+
placement?: 'footer' | 'inline';
|
|
113
203
|
}>;
|
|
114
204
|
export const Dialog: ComponentType<{
|
|
115
205
|
open: boolean;
|
|
@@ -200,6 +290,20 @@ declare module 'deveye-sdk-client' {
|
|
|
200
290
|
onClose: () => void;
|
|
201
291
|
busy?: boolean;
|
|
202
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;
|
|
203
307
|
export const FeatureSettingsButton: ComponentType<{
|
|
204
308
|
scope:
|
|
205
309
|
| { kind: 'feature'; feature: FeatureId }
|
|
@@ -210,7 +314,12 @@ declare module 'deveye-sdk-client' {
|
|
|
210
314
|
itemLabel: string;
|
|
211
315
|
shareable?: boolean;
|
|
212
316
|
};
|
|
213
|
-
|
|
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';
|
|
214
323
|
label?: string;
|
|
215
324
|
/** The tab a click opens (one of the manifest's tab ids); the first by default. */
|
|
216
325
|
initialSection?: string;
|
|
@@ -265,6 +374,22 @@ declare module 'deveye-sdk-client' {
|
|
|
265
374
|
* cannot be projected) keeps its own wording.
|
|
266
375
|
*/
|
|
267
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;
|
|
268
393
|
/** The canonical settings row classes (channelRow, field, sectionHint...). */
|
|
269
394
|
export const settingsStyles: Readonly<Record<string, string>>;
|
|
270
395
|
/** A plain count on a home card: a big number, a noun, a secondary line. */
|
|
@@ -463,6 +588,19 @@ declare module 'deveye-sdk-client' {
|
|
|
463
588
|
* `undefined`. Use it on every `<a href>` you do not write yourself.
|
|
464
589
|
*/
|
|
465
590
|
export function safeHref(url: string | null | undefined): string | undefined;
|
|
591
|
+
/**
|
|
592
|
+
* A v4 UUID, secure context or not. `crypto.randomUUID` is only exposed over
|
|
593
|
+
* HTTPS or on localhost, so an instance served in the clear on a LAN address
|
|
594
|
+
* does not have it: use this instead of calling it yourself.
|
|
595
|
+
*/
|
|
596
|
+
export function randomUuid(): string;
|
|
597
|
+
/**
|
|
598
|
+
* Writes `value` to the clipboard and says whether it worked: on `false` the
|
|
599
|
+
* gesture still needs to be confirmed some other way, never silently dropped.
|
|
600
|
+
* `navigator.clipboard` only exists in a secure context, so this falls back to
|
|
601
|
+
* an offscreen selection. Never call the browser API directly.
|
|
602
|
+
*/
|
|
603
|
+
export function copyText(value: string): Promise<boolean>;
|
|
466
604
|
/**
|
|
467
605
|
* The DevEye version this interface was built from: what an agent's
|
|
468
606
|
* reported version is compared against to offer a self-update.
|
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
|
@@ -127,8 +127,9 @@ export type NativeCapability =
|
|
|
127
127
|
| 'live.publish'
|
|
128
128
|
/**
|
|
129
129
|
* Read accounts (id, email, username, creation date): the caller's own in a
|
|
130
|
-
* handler, any account from a service
|
|
131
|
-
* not to a workspace (a subscription, a
|
|
130
|
+
* handler, any account from a service, by id, by email or by search. For
|
|
131
|
+
* what belongs to an account and not to a workspace (a subscription, a
|
|
132
|
+
* receipt to address).
|
|
132
133
|
*/
|
|
133
134
|
| 'accounts.read';
|
|
134
135
|
|
|
@@ -236,6 +237,12 @@ export interface FeatureManifest<Id extends FeatureId = FeatureId> {
|
|
|
236
237
|
itemNounGender?: 'm' | 'f';
|
|
237
238
|
/** Feature-scope reusable settings (API keys, destinations). Opens the Sources tab. */
|
|
238
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 };
|
|
239
246
|
/**
|
|
240
247
|
* The feature serves something under domain names the workspace owns (a
|
|
241
248
|
* public page, a mailbox). Opens the Domains tab, which DevEye renders:
|
|
@@ -473,6 +480,11 @@ export function validateManifest(m: FeatureManifest): void {
|
|
|
473
480
|
}
|
|
474
481
|
}
|
|
475
482
|
|
|
483
|
+
if (m.notifies && !m.notifications?.hint.trim()) {
|
|
484
|
+
fail(m.id, 'notifies requires notifications.hint: say when the feature notifies');
|
|
485
|
+
}
|
|
486
|
+
if (m.notifications && !m.notifies) fail(m.id, 'notifications.hint without notifies');
|
|
487
|
+
|
|
476
488
|
if (m.domains) {
|
|
477
489
|
if (!m.domains.hint.trim()) fail(m.id, 'domains: empty hint');
|
|
478
490
|
if (!m.domains.service.trim()) fail(m.id, 'domains: empty service');
|
|
@@ -532,6 +544,7 @@ export function externalDescriptorOf(
|
|
|
532
544
|
itemNoun: m.itemNoun,
|
|
533
545
|
itemNounGender: m.itemNounGender,
|
|
534
546
|
sources: m.sources,
|
|
547
|
+
notifications: m.notifications,
|
|
535
548
|
shareTier: m.shareTier
|
|
536
549
|
};
|
|
537
550
|
}
|
package/src/sdk/server.ts
CHANGED
|
@@ -307,6 +307,13 @@ export interface SdkAccounts {
|
|
|
307
307
|
find(userId: number): Promise<SdkAccount | null>;
|
|
308
308
|
findByEmail(email: string): Promise<SdkAccount | null>;
|
|
309
309
|
list(userIds: readonly number[]): Promise<readonly SdkAccount[]>;
|
|
310
|
+
/**
|
|
311
|
+
* Accounts whose username or email contains `query`, case-insensitively,
|
|
312
|
+
* by username. An all-digit query also matches that account id, listed
|
|
313
|
+
* first. An empty query returns the first accounts. `limit` defaults to 20
|
|
314
|
+
* and is capped at 50.
|
|
315
|
+
*/
|
|
316
|
+
search(query: string, limit?: number): Promise<readonly SdkAccount[]>;
|
|
310
317
|
}
|
|
311
318
|
|
|
312
319
|
/**
|
|
@@ -888,6 +895,13 @@ export interface SdkPublicRouteOptions {
|
|
|
888
895
|
exposure?: 'everywhere' | 'app';
|
|
889
896
|
/** Also hand the handler the undecoded body (`SdkPublicRequest.rawBody`). JSON bodies only. */
|
|
890
897
|
rawBody?: boolean;
|
|
898
|
+
/**
|
|
899
|
+
* Largest body this route accepts, in bytes. Size it on the biggest
|
|
900
|
+
* legitimate call: the host default is a megabyte, which is orders of
|
|
901
|
+
* magnitude above what a beacon or a form sends, and every byte of it is
|
|
902
|
+
* parsed before your schema sees anything.
|
|
903
|
+
*/
|
|
904
|
+
bodyLimit?: number;
|
|
891
905
|
}
|
|
892
906
|
|
|
893
907
|
/** What a redeemed ticket gives a public route back (see `SdkSecrecy.ticket`). */
|
|
@@ -901,6 +915,37 @@ export interface SdkRedeemedTicket {
|
|
|
901
915
|
|
|
902
916
|
export type SdkPublicHandler = (req: SdkPublicRequest, reply: SdkPublicReply) => Promise<unknown>;
|
|
903
917
|
|
|
918
|
+
/**
|
|
919
|
+
* The body of a streamed route: never decoded, never buffered. The HOST counts
|
|
920
|
+
* the bytes and cuts the connection at `maxBytes`, so a module that forgets to
|
|
921
|
+
* count cannot open a bottomless pit.
|
|
922
|
+
*/
|
|
923
|
+
export interface SdkPublicStreamBody {
|
|
924
|
+
/** The announced `Content-Length`, `null` when chunked. Unverified: compare it with what you read. */
|
|
925
|
+
contentLength: number | null;
|
|
926
|
+
/** The bytes, in order. Throws `FeatureError('validation')` past `maxBytes`. Consumable once. */
|
|
927
|
+
bytes(): AsyncIterable<Buffer>;
|
|
928
|
+
}
|
|
929
|
+
|
|
930
|
+
/** The request of a streamed route: the same, its decoded body replaced by its bytes. */
|
|
931
|
+
export interface SdkPublicStreamRequest extends Omit<SdkPublicRequest, 'body' | 'rawBody'> {
|
|
932
|
+
body: SdkPublicStreamBody;
|
|
933
|
+
}
|
|
934
|
+
|
|
935
|
+
export interface SdkPublicStreamRouteOptions {
|
|
936
|
+
/** Counts REQUESTS, not bytes: a 5 GiB upload is one request. Not what protects the disk. */
|
|
937
|
+
rateLimit?: { max: number; timeWindow: string };
|
|
938
|
+
/** Absolute ceiling of the body, enforced by the host. A per-account ceiling is yours to check on top. */
|
|
939
|
+
maxBytes: number;
|
|
940
|
+
/** Written, not defaulted: a route that swallows gigabytes never opens on the public listener by omission. */
|
|
941
|
+
exposure: 'app';
|
|
942
|
+
}
|
|
943
|
+
|
|
944
|
+
export type SdkPublicStreamHandler = (
|
|
945
|
+
req: SdkPublicStreamRequest,
|
|
946
|
+
reply: SdkPublicReply
|
|
947
|
+
) => Promise<unknown>;
|
|
948
|
+
|
|
904
949
|
/**
|
|
905
950
|
* Where a module declares its public routes (capability `'routes.public'`).
|
|
906
951
|
* Paths are absolute (`/t.js`, `/api/t/b`); a path the host already serves
|
|
@@ -909,11 +954,25 @@ export type SdkPublicHandler = (req: SdkPublicRequest, reply: SdkPublicReply) =>
|
|
|
909
954
|
export interface SdkPublicApp {
|
|
910
955
|
get(path: string, opts: SdkPublicRouteOptions, handler: SdkPublicHandler): void;
|
|
911
956
|
post(path: string, opts: SdkPublicRouteOptions, handler: SdkPublicHandler): void;
|
|
957
|
+
/**
|
|
958
|
+
* A POST whose body is NOT decoded: the host hands it over as a bounded
|
|
959
|
+
* stream, whatever its content type. For what no parser should ever hold in
|
|
960
|
+
* full, an uploaded file. No path parameter, app origin only, and kept out
|
|
961
|
+
* of the CORS-widened paths: authenticate it with a ticket (`SdkSecrecy.ticket`).
|
|
962
|
+
*/
|
|
963
|
+
postStream(
|
|
964
|
+
path: string,
|
|
965
|
+
opts: SdkPublicStreamRouteOptions,
|
|
966
|
+
handler: SdkPublicStreamHandler
|
|
967
|
+
): void;
|
|
912
968
|
}
|
|
913
969
|
|
|
914
970
|
/**
|
|
915
971
|
* A background worker. Started during boot (awaited, before the agent socket
|
|
916
|
-
* layer registers), stopped on shutdown.
|
|
972
|
+
* layer registers), stopped on shutdown. A full-stop maintenance of the feature
|
|
973
|
+
* also stops it at runtime, then calls `start()` again on the same object: stop
|
|
974
|
+
* must resolve once the work in flight is finished or interrupted, and leave
|
|
975
|
+
* nothing that would break a second start. Stopping a stopped service is a no-op.
|
|
917
976
|
*/
|
|
918
977
|
export interface FeatureService {
|
|
919
978
|
start(): void | Promise<void>;
|
|
@@ -989,6 +1048,7 @@ export interface FeatureServiceDeps<Repo = unknown> {
|
|
|
989
1048
|
/**
|
|
990
1049
|
* The app's standard loop: setInterval + reentrancy guard + unref, the
|
|
991
1050
|
* exact pattern of every native service. Use it instead of rolling your own.
|
|
1051
|
+
* `stop()` resolves once the tick in flight, if any, has finished: await it.
|
|
992
1052
|
*/
|
|
993
1053
|
createTicker(opts: { intervalMs: number; tick(): Promise<void> }): FeatureService;
|
|
994
1054
|
logger: SdkLogger;
|
|
@@ -1080,6 +1140,13 @@ export interface SdkCopyPlan {
|
|
|
1080
1140
|
* token of the origin workspace, a history the destination rebuilds.
|
|
1081
1141
|
*/
|
|
1082
1142
|
drops: readonly string[];
|
|
1143
|
+
/**
|
|
1144
|
+
* What the copy DOES carry and nobody would guess: a secret the destination
|
|
1145
|
+
* will be able to read, such as a password the item authenticates with.
|
|
1146
|
+
* Optional, because most items have nothing to declare here; say it and the
|
|
1147
|
+
* confirmation lists it, or whoever copies never learns it.
|
|
1148
|
+
*/
|
|
1149
|
+
carries?: readonly string[];
|
|
1083
1150
|
}
|
|
1084
1151
|
|
|
1085
1152
|
/** See {@link FeatureItemsEntry.copy}. */
|
|
@@ -1150,6 +1217,12 @@ export interface SdkMovePlan {
|
|
|
1150
1217
|
* Say it here or the caller discovers it afterwards.
|
|
1151
1218
|
*/
|
|
1152
1219
|
drops: readonly string[];
|
|
1220
|
+
/**
|
|
1221
|
+
* What follows the item and nobody would guess: a secret the destination
|
|
1222
|
+
* workspace will be able to read. Optional, same contract as
|
|
1223
|
+
* {@link SdkCopyPlan.carries}.
|
|
1224
|
+
*/
|
|
1225
|
+
carries?: readonly string[];
|
|
1153
1226
|
/**
|
|
1154
1227
|
* Encrypted cells to convert, so the confirmation can say how much rather
|
|
1155
1228
|
* than spin. An estimate is fine; zero is a legitimate answer.
|
package/src/sdk/testing.test.ts
CHANGED
|
@@ -67,6 +67,28 @@ test('createTestServiceDeps: one store per workspace, hand-driven tickers, a wra
|
|
|
67
67
|
assert.equal((await deps.devicesFor(1).list()).length, 1);
|
|
68
68
|
});
|
|
69
69
|
|
|
70
|
+
test('the harness searches accounts like the app: substring, exact id first, capped', async () => {
|
|
71
|
+
const account = (id: number, username: string) => ({
|
|
72
|
+
id,
|
|
73
|
+
username,
|
|
74
|
+
email: `${username}@example.com`,
|
|
75
|
+
isAdmin: false,
|
|
76
|
+
created: 0
|
|
77
|
+
});
|
|
78
|
+
const { accounts } = createTestServiceDeps({
|
|
79
|
+
accounts: [account(7, 'zoe'), account(12, 'Alice'), account(3, 'bob12')]
|
|
80
|
+
});
|
|
81
|
+
const ids = async (query: string, limit?: number) =>
|
|
82
|
+
(await accounts.search(query, limit)).map((a) => a.id);
|
|
83
|
+
|
|
84
|
+
assert.deepEqual(await ids(' '), [12, 3, 7], 'an empty query lists by username');
|
|
85
|
+
assert.deepEqual(await ids('aLiCe@EXAMPLE'), [12]);
|
|
86
|
+
assert.deepEqual(await ids('12'), [12, 3], 'the exact id comes before a substring hit');
|
|
87
|
+
assert.deepEqual(await ids('12abc'), []);
|
|
88
|
+
assert.deepEqual(await ids('', 1), [12]);
|
|
89
|
+
assert.equal((await ids('', 0)).length, 1, 'a limit below one is raised to one');
|
|
90
|
+
});
|
|
91
|
+
|
|
70
92
|
test('the harness scopes domains to the workspace, and finds a host whatever its spelling', async () => {
|
|
71
93
|
const domains = [
|
|
72
94
|
testDomain({ id: 1, host: 'a.example.com' }),
|
package/src/sdk/testing.ts
CHANGED
|
@@ -673,7 +673,27 @@ export function createTestServiceDeps<Repo = undefined>(
|
|
|
673
673
|
) ?? null
|
|
674
674
|
),
|
|
675
675
|
list: (userIds) =>
|
|
676
|
-
Promise.resolve((overrides.accounts ?? []).filter((a) => userIds.includes(a.id)))
|
|
676
|
+
Promise.resolve((overrides.accounts ?? []).filter((a) => userIds.includes(a.id))),
|
|
677
|
+
search: (query, limit) => {
|
|
678
|
+
const needle = query.trim().toLowerCase();
|
|
679
|
+
const id = /^\d+$/.test(needle) ? Number(needle) : null;
|
|
680
|
+
const found = (overrides.accounts ?? [])
|
|
681
|
+
.filter(
|
|
682
|
+
(a) =>
|
|
683
|
+
needle === '' ||
|
|
684
|
+
a.id === id ||
|
|
685
|
+
a.username.toLowerCase().includes(needle) ||
|
|
686
|
+
a.email.toLowerCase().includes(needle)
|
|
687
|
+
)
|
|
688
|
+
.sort(
|
|
689
|
+
(a, b) =>
|
|
690
|
+
Number(b.id === id) - Number(a.id === id) ||
|
|
691
|
+
a.username.localeCompare(b.username)
|
|
692
|
+
);
|
|
693
|
+
return Promise.resolve(
|
|
694
|
+
found.slice(0, Math.min(Math.max(1, Math.trunc(limit ?? 20)), 50))
|
|
695
|
+
);
|
|
696
|
+
}
|
|
677
697
|
},
|
|
678
698
|
audit: (entry) => {
|
|
679
699
|
recorded.audits.push({ action: entry.action, description: entry.description });
|