@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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deveye/types",
3
- "version": "0.19.2",
3
+ "version": "0.20.1",
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: {
@@ -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 — le besoin de très loin le plus courant. */
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
  }
@@ -39,7 +39,8 @@ export const nativeHomeFeatureIdSchema = z.enum([
39
39
  'osint',
40
40
  'cve',
41
41
  'mailserver',
42
- 'convert'
42
+ 'convert',
43
+ 'invoicing'
43
44
  ]);
44
45
  export type NativeHomeFeatureId = z.infer<typeof nativeHomeFeatureIdSchema>;
45
46
 
@@ -201,6 +201,7 @@ export const TOPIC_FEATURE: Record<NativeLiveTopic, WorkspaceFeatureId | null> =
201
201
  cve: 'cve',
202
202
  mailserver: 'mailserver',
203
203
  convert: 'convert',
204
+ invoicing: 'invoicing',
204
205
  workspace: null,
205
206
  home: null,
206
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>;
@@ -42,7 +42,8 @@ export const nativeNotificationFeatureSchema = z.enum([
42
42
  'database',
43
43
  'deploy',
44
44
  'backup',
45
- 'convert'
45
+ 'convert',
46
+ 'invoicing'
46
47
  ]);
47
48
  export type NativeNotificationFeature = z.infer<typeof nativeNotificationFeatureSchema>;
48
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({
@@ -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>;
@@ -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;
@@ -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({ domains: z.array(featureDomainSchema) })
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,
@@ -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
- * Le bouton d'enregistrement d'un panneau de réglages : « Enregistrement… »
186
- * pendant l'aller-retour, « Enregistré » quelques secondes, puis l'intitulé
187
- * de départ. Les erreurs restent au panneau, elles ne s'effacent pas seules.
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
- 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';
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. */
@@ -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
+ });
@@ -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 reachable
790
- * without the VPN when the host has a public surface (else the same).
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.