@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 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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deveye/types",
3
- "version": "0.19.1",
3
+ "version": "0.20.0",
4
4
  "description": "Shared contracts (types + zod schemas) for DevEye apps",
5
5
  "main": "src/index.ts",
6
6
  "types": "src/index.ts",
@@ -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 — affichée sous la ligne de la
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 — le besoin de très loin le plus courant. */
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
  }
@@ -38,7 +38,9 @@ export const nativeHomeFeatureIdSchema = z.enum([
38
38
  'audience',
39
39
  'osint',
40
40
  'cve',
41
- 'mailserver'
41
+ 'mailserver',
42
+ 'convert',
43
+ 'invoicing'
42
44
  ]);
43
45
  export type NativeHomeFeatureId = z.infer<typeof nativeHomeFeatureIdSchema>;
44
46
 
@@ -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>;
@@ -41,7 +41,9 @@ export const nativeNotificationFeatureSchema = z.enum([
41
41
  'sentinel',
42
42
  'database',
43
43
  'deploy',
44
- 'backup'
44
+ 'backup',
45
+ 'convert',
46
+ 'invoicing'
45
47
  ]);
46
48
  export type NativeNotificationFeature = z.infer<typeof nativeNotificationFeatureSchema>;
47
49
 
@@ -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. */
@@ -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>;
@@ -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,
@@ -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
- options: readonly { value: T; label: string; title?: string }[];
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
- * Le bouton d'enregistrement d'un panneau de réglages : « Enregistrement… »
103
- * pendant l'aller-retour, « Enregistré » quelques secondes, puis l'intitulé
104
- * de départ. Les erreurs restent au panneau, elles ne s'effacent pas seules.
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
- variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
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.
@@ -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: false,
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
+ });
@@ -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. For what belongs to an account and
131
- * not to a workspace (a subscription, a receipt to address).
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.
@@ -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' }),
@@ -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 });