@deveye/types 0.22.1 → 0.23.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/README.md CHANGED
@@ -1,29 +1,38 @@
1
1
  # @deveye/types
2
2
 
3
- Les contrats partagés de [DevEye](https://github.com/Gerem66/DevEye) : types
4
- TypeScript et schémas zod, consommés par le serveur, le client et les modules
5
- de features.
3
+ The shared contracts of [DevEye](https://github.com/Gerem66/DevEye): TypeScript
4
+ types and zod schemas, consumed by the server, the client and the feature
5
+ modules.
6
6
 
7
- Le package sert ses sources directement (`src/*.ts`, aucun build) :
7
+ The package ships its sources as is (`src/*.ts`, no build step). Its entries,
8
+ as `package.json` exports them:
8
9
 
9
- - **`@deveye/types`** — le domaine transverse (espaces, rôles, live, partage…),
10
- les protocoles (enveloppe WS, agent), le registre d'identité des features.
11
- - **`@deveye/types/sdk`** — le contrat des modules de features : `FeatureManifest`,
12
- `validateManifest`, ids `x-<slug>`.
13
- - **`@deveye/types/sdk/server`** — le contexte serveur d'un module (handlers,
14
- store, façade, service).
15
- - **`@deveye/types/sdk/client`** — les contrats de l'entrée client d'un module.
16
- - **`@deveye/types/sdk/testing`** — le harnais de test en mémoire des handlers.
10
+ - **`@deveye/types`**: the cross-cutting domain (workspaces, roles, live
11
+ presence, sharing...), the protocols (WebSocket envelope, errors, agent) and
12
+ the feature identity registry.
13
+ - **`@deveye/types/sdk`**: the contract of a feature module: `FeatureManifest`
14
+ and `validateManifest`, the `x-<slug>` ids, the provider contracts modules
15
+ offer one another, the look of a public page, the device a form offers as a
16
+ relay.
17
+ - **`@deveye/types/sdk/server`**: what a module's handlers and background
18
+ service receive (context, store, facade, service deps), plus the server
19
+ helpers (SSRF guard, environment spec, domain names, item copy and move, the
20
+ holder's data export, sealed file container, device relay, download headers).
21
+ - **`@deveye/types/sdk/client`**: the contracts of a module's client entry.
22
+ - **`@deveye/types/sdk/testing`**: the in-memory harness for handlers,
23
+ services and domain hooks.
17
24
 
18
- Le portrait typé du barrel `deveye-sdk-client` (le runtime que l'app fournit
19
- aux modules) est publié ici aussi (`src/sdk/client-ambient.d.ts`) ; la CI de
20
- DevEye vérifie mécaniquement que le vrai barrel l'honore.
25
+ The typed portrait of `deveye-sdk-client`, the runtime barrel the app provides
26
+ to modules, is published here too (`src/sdk/client-ambient.d.ts`); DevEye's CI
27
+ checks mechanically that the real barrel honours it.
21
28
 
22
- Pour écrire un module : partir du
23
- [template](https://github.com/Gerem66/DevEye-Feature-Template) et sa doc.
29
+ To write a module, start from the
30
+ [template](https://github.com/Gerem66/DevEye-Feature-Template) and its docs.
24
31
 
25
- ## Licence
32
+ ## License
26
33
 
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).
34
+ [MIT](LICENSE). A module built on this package is licensed as its author sees
35
+ fit: DevEye's core is AGPL-3.0, with an additional permission for what reaches
36
+ the app only through this SDK
37
+ ([`LICENSING.md`](https://github.com/Gerem66/DevEye/blob/main/LICENSING.md) in
38
+ the app's repository).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deveye/types",
3
- "version": "0.22.1",
3
+ "version": "0.23.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,45 @@
1
+ import { z } from 'zod';
2
+
3
+ /**
4
+ * An external dependency of the instance (a payment provider, an object store,
5
+ * a third-party API) as the administrator's "Services externes" page shows it.
6
+ * Services set up by each workspace (its own webhook, its own API key) are not
7
+ * the instance's and never appear there.
8
+ */
9
+
10
+ /** `inactive`: not configured on this instance, on purpose or not yet. */
11
+ export const externalServiceStateSchema = z.enum(['ok', 'degraded', 'down', 'inactive']);
12
+ export type ExternalServiceState = z.infer<typeof externalServiceStateSchema>;
13
+
14
+ /** One "label: value" line of a service's card. */
15
+ export const externalServiceFactSchema = z.object({
16
+ label: z.string().min(1),
17
+ value: z.string(),
18
+ tone: z.enum(['success', 'warning', 'danger']).optional()
19
+ });
20
+ export type ExternalServiceFact = z.infer<typeof externalServiceFactSchema>;
21
+
22
+ /** A gauge: `used` out of `limit`, in bytes or as a plain count. */
23
+ export const externalServiceMeterSchema = z.object({
24
+ label: z.string().min(1),
25
+ used: z.number().nonnegative(),
26
+ limit: z.number().positive(),
27
+ unit: z.enum(['bytes', 'count']),
28
+ note: z.string().optional()
29
+ });
30
+ export type ExternalServiceMeter = z.infer<typeof externalServiceMeterSchema>;
31
+
32
+ export const externalServiceSchema = z.object({
33
+ /** Unique within its contributor; the host prefixes it with the module id. */
34
+ id: z.string().min(1),
35
+ /** "Stripe", "Open-Meteo". */
36
+ name: z.string().min(1),
37
+ /** Who runs it, when the name does not say: "OVHcloud". */
38
+ provider: z.string().optional(),
39
+ state: externalServiceStateSchema,
40
+ /** One sentence for a person, never a stack trace. */
41
+ summary: z.string().optional(),
42
+ facts: z.array(externalServiceFactSchema).optional(),
43
+ meters: z.array(externalServiceMeterSchema).optional()
44
+ });
45
+ export type ExternalService = z.infer<typeof externalServiceSchema>;
@@ -129,12 +129,13 @@ export const shortcutItemSchema = z.object({
129
129
  export type ShortcutItem = z.infer<typeof shortcutItemSchema>;
130
130
 
131
131
  /**
132
- * Plafonds d'une section et d'un dossier. Exportés parce que le client doit
132
+ * Plafonds d'une section, d'un dossier et de la barre. Exportés parce que le client doit
133
133
  * refuser avant d'écrire : une disposition qui dépasse ne passe plus la
134
134
  * validation, et le client la relirait vide au démarrage suivant.
135
135
  */
136
136
  export const HOME_SECTION_MAX_TILES = 60;
137
137
  export const HOME_FOLDER_MAX_ITEMS = 20;
138
+ export const HOME_TOPBAR_MAX_WIDGETS = 10;
138
139
 
139
140
  /**
140
141
  * Un dossier de la grille : plusieurs fonctionnalités derrière une seule tuile,
@@ -241,7 +242,7 @@ export type HomeSection = z.infer<typeof homeSectionSchema>;
241
242
 
242
243
  export const homeLayoutSchema = z.object({
243
244
  /** Navbar mini-widgets — not a grid section, edited in the navbar itself. */
244
- topbar: z.array(homeTopbarWidgetIdSchema).max(10),
245
+ topbar: z.array(homeTopbarWidgetIdSchema).max(HOME_TOPBAR_MAX_WIDGETS),
245
246
  /** Ordered grid sections. Empty by default: a fresh home shows none. */
246
247
  sections: z.array(homeSectionSchema).max(12)
247
248
  });
@@ -236,11 +236,17 @@ export const agentInfoSchema = z.object({
236
236
  /** OS account the agent runs as (e.g. `root`, `deploy`). */
237
237
  user: z.string().max(128),
238
238
  /**
239
- * How the agent is installed for persistence: `none` (transient run), `user`
240
- * (per-user autostart, login session) or `system` (root/system service, boot).
241
- * Optional + defaulted so reports from agents predating this field still parse.
239
+ * Which service carries the agent: `none` (started by hand), `user` (per-user
240
+ * service) or `system` (root/system service). Whether it comes back after a
241
+ * reboot is `autostart`.
242
242
  */
243
243
  serviceScope: agentServiceScopeSchema.default('none'),
244
+ /**
245
+ * The service is armed for the next boot (or login, for a per-user service on
246
+ * macOS and Windows). Always `false` without a service. Absent from agents too
247
+ * old to arm or disarm their service on their own.
248
+ */
249
+ autostart: z.boolean().optional(),
244
250
  /** True when launched by a service manager (so a self-update just exits to be relaunched). */
245
251
  managed: z.boolean().default(false),
246
252
  /**
@@ -1,5 +1,6 @@
1
1
  import { z } from 'zod';
2
2
  import { seatCapsSchema } from '../domain/admission';
3
+ import { externalServiceSchema } from '../domain/externalService';
3
4
  import { featureMaintenanceLevelSchema, MAINTENANCE_MESSAGE_MAX } from '../domain/maintenance';
4
5
  import { userRoleSchema } from '../domain/role';
5
6
  import { userStatusSchema } from '../domain/user';
@@ -174,6 +175,30 @@ export const adminMaintenanceDismissNotice = {
174
175
  output: z.object({})
175
176
  };
176
177
 
178
+ const seatUseSchema = z.object({
179
+ /** `null`: no cap. */
180
+ cap: z.number().int().positive().nullable(),
181
+ present: z.number().int().nonnegative(),
182
+ waiting: z.number().int().nonnegative()
183
+ });
184
+
185
+ /** The "Services externes" page: every external dependency of the instance, then this server's seats. */
186
+ export const adminExternalServicesSchema = z.object({
187
+ services: z.array(externalServiceSchema),
188
+ /** This server's simultaneous seats, the only limit on how many accounts it serves at once. */
189
+ seats: z.object({ free: seatUseSchema, paid: seatUseSchema }),
190
+ /** Milliseconds: when the services were last checked. */
191
+ checkedAt: z.number().int().nonnegative()
192
+ });
193
+ export type AdminExternalServices = z.infer<typeof adminExternalServicesSchema>;
194
+
195
+ /** `refresh`: check again now rather than answer the last check (kept a few minutes). */
196
+ export const adminExternalServices = {
197
+ command: 'admin.externalServices' as const,
198
+ input: z.object({ refresh: z.boolean() }),
199
+ output: adminExternalServicesSchema
200
+ };
201
+
177
202
  export const adminCommands = [
178
203
  adminUserList,
179
204
  adminSetUserRole,
@@ -185,5 +210,6 @@ export const adminCommands = [
185
210
  adminMaintenancePriority,
186
211
  adminMaintenanceSignups,
187
212
  adminMaintenanceSeats,
188
- adminMaintenanceDismissNotice
213
+ adminMaintenanceDismissNotice,
214
+ adminExternalServices
189
215
  ] as const;
@@ -75,13 +75,15 @@ export const agentLifecycle = {
75
75
  };
76
76
 
77
77
  /**
78
- * Enable/disable the agent's per-user autostart (survives reboot, no privilege).
79
- * Pushes `agent.service` to the connected agent (`install-user`/`uninstall-user`).
78
+ * Arm or disarm the agent's service for the next boot, whatever its privileges.
79
+ * Pushes `agent.service` (`autostart-on`/`autostart-off`). A system service needs
80
+ * root: an agent without it replies `needsManualCommand`, and the UI shows
81
+ * `manualCommand` to run on the device.
80
82
  */
81
83
  export const agentSetAutostart = {
82
84
  command: 'agent.setAutostart' as const,
83
85
  input: z.object({ deviceId, enabled: z.boolean() }),
84
- output: z.object({ device: deviceSchema })
86
+ output: z.object({ device: deviceSchema, manualCommand: z.string() })
85
87
  };
86
88
 
87
89
  /**
package/src/index.ts CHANGED
@@ -1,5 +1,15 @@
1
- export { clientMessageSchema, serverMessageSchema } from './protocol/envelope';
2
- export type { ClientMessage, ConnectionState, ServerMessage } from './protocol/envelope';
1
+ export {
2
+ clientMessageSchema,
3
+ REQUEST_PROGRESS_EVENT,
4
+ requestProgressSchema,
5
+ serverMessageSchema
6
+ } from './protocol/envelope';
7
+ export type {
8
+ ClientMessage,
9
+ ConnectionState,
10
+ RequestProgress,
11
+ ServerMessage
12
+ } from './protocol/envelope';
3
13
  export { ErrorCodeSchema, ProtocolErrorSchema } from './protocol/error';
4
14
  export type { ErrorCode, ProtocolError } from './protocol/error';
5
15
  export { err, ok, resultSchema } from './protocol/result';
@@ -364,6 +374,18 @@ export {
364
374
  SESSION_ACTIVE_COMMAND
365
375
  } from './domain/admission';
366
376
  export type { QueueRefusal, Seat, SeatCaps } from './domain/admission';
377
+ export {
378
+ externalServiceFactSchema,
379
+ externalServiceMeterSchema,
380
+ externalServiceSchema,
381
+ externalServiceStateSchema
382
+ } from './domain/externalService';
383
+ export type {
384
+ ExternalService,
385
+ ExternalServiceFact,
386
+ ExternalServiceMeter,
387
+ ExternalServiceState
388
+ } from './domain/externalService';
367
389
  export {
368
390
  featureMaintenanceLevelSchema,
369
391
  MAINTENANCE_CLOSE_CODE,
@@ -519,6 +541,7 @@ export {
519
541
  nativeHomeTopbarWidgetIdSchema,
520
542
  HOME_FEATURE_IDS,
521
543
  HOME_FOLDER_MAX_ITEMS,
544
+ HOME_TOPBAR_MAX_WIDGETS,
522
545
  HOME_SECTION_MAX_TILES,
523
546
  isFeatureTile,
524
547
  isHomeFolder,
@@ -898,6 +921,8 @@ export type {
898
921
  export {
899
922
  adminCommands,
900
923
  adminDeleteUser,
924
+ adminExternalServices,
925
+ adminExternalServicesSchema,
901
926
  adminMaintenanceDismissNotice,
902
927
  adminMaintenanceFeature,
903
928
  adminMaintenanceGet,
@@ -911,7 +936,7 @@ export {
911
936
  adminUserList,
912
937
  adminUserSchema
913
938
  } from './features/admin';
914
- export type { AdminMaintenance, AdminUser } from './features/admin';
939
+ export type { AdminExternalServices, AdminMaintenance, AdminUser } from './features/admin';
915
940
  export {
916
941
  debugBenchCatalog,
917
942
  debugBenchContextSchema,
@@ -76,14 +76,15 @@ export const agentUpdatedMessagePayloadSchema = z.object({
76
76
 
77
77
  /**
78
78
  * Persistence/privilege action the server can ask the agent to perform:
79
- * - `install-user` install a per-user autostart (no privilege needed),
80
- * - `uninstall-user` remove it,
81
- * - `elevate` (try to) become a root/system service — see the hybrid flow,
82
- * - `drop` go back from system/root to a per-user service.
79
+ * - `autostart-on` start with the machine (or the session): arm the installed
80
+ * service, or install one matching the agent's privileges when there is none,
81
+ * - `autostart-off` disarm the service; the agent keeps running until the next boot,
82
+ * - `elevate` (try to) become a root/system service, see the hybrid flow,
83
+ * - `drop` go back from system/root to a per-user service.
83
84
  */
84
85
  export const agentServiceActionSchema = z.enum([
85
- 'install-user',
86
- 'uninstall-user',
86
+ 'autostart-on',
87
+ 'autostart-off',
87
88
  'elevate',
88
89
  'drop'
89
90
  ]);
@@ -1062,7 +1063,7 @@ export const syncShareAssignmentSchema = z.object({
1062
1063
  */
1063
1064
  rateUpBps: z.number().int().positive().nullable().default(null),
1064
1065
  /** Rétention de `.deveye-trash/`, en jours. */
1065
- trashKeepDays: z.number().int().positive().max(3650).default(30),
1066
+ trashKeepDays: z.number().int().positive().max(3650).default(7),
1066
1067
  /**
1067
1068
  * Set on an end-to-end encrypted share: the agent hashes with a key,
1068
1069
  * encrypts what it uploads and decrypts what it installs. `wrappedKey` is
@@ -1270,7 +1271,12 @@ export const AGENT_SYNC_DELETE = 'sync.delete' as const;
1270
1271
  export const agentSyncDeletePayloadSchema = z.object({
1271
1272
  opId: syncOpId,
1272
1273
  shareId: z.number().int().positive(),
1273
- relPath: syncRelPath
1274
+ relPath: syncRelPath,
1275
+ /**
1276
+ * Asked for by the user: the file goes to the trash even if it changed since
1277
+ * the scan or was never indexed (unreadable, unportable name).
1278
+ */
1279
+ force: z.boolean().optional()
1274
1280
  });
1275
1281
  export type AgentSyncDeletePayload = z.infer<typeof agentSyncDeletePayloadSchema>;
1276
1282
 
@@ -36,4 +36,21 @@ export const serverMessageSchema = z.object({
36
36
 
37
37
  export type ServerMessage = z.infer<typeof serverMessageSchema>;
38
38
 
39
+ /**
40
+ * Progress of a pending command, pushed to its caller only (the `progress` of a
41
+ * handler context), as an unsolicited event carrying the request it belongs to.
42
+ * The client re-arms the request's timeout on each one: a command that keeps
43
+ * reporting never times out, `timeoutMs` bounds its silence.
44
+ */
45
+ export const REQUEST_PROGRESS_EVENT = 'request.progress' as const;
46
+
47
+ export const requestProgressSchema = z.object({
48
+ requestId: z.string().min(1),
49
+ done: z.number().int().nonnegative().optional(),
50
+ total: z.number().int().nonnegative().optional(),
51
+ step: z.string().max(200).optional()
52
+ });
53
+
54
+ export type RequestProgress = z.infer<typeof requestProgressSchema>;
55
+
39
56
  export type ConnectionState = 'idle' | 'connecting' | 'open' | 'closing' | 'closed' | 'error';
@@ -29,6 +29,7 @@ declare module 'deveye-sdk-client' {
29
29
  FeatureId,
30
30
  MinimalUser,
31
31
  PathExclusionKind,
32
+ RequestProgress,
32
33
  User,
33
34
  WorkspaceCapability
34
35
  } from '@deveye/types';
@@ -52,6 +53,26 @@ declare module 'deveye-sdk-client' {
52
53
  export const TextInput: ComponentType<
53
54
  InputHTMLAttributes<HTMLInputElement> & { enableShowHideButton?: boolean; error?: string }
54
55
  >;
56
+ export interface ActionMenuItem {
57
+ label: string;
58
+ icon?: string;
59
+ onSelect: () => void;
60
+ /** A destructive action: shown in red. */
61
+ danger?: boolean;
62
+ disabled?: boolean;
63
+ /** What the action does, in one sentence, under the label. */
64
+ detail?: string;
65
+ }
66
+ export interface ActionMenuProps {
67
+ items: readonly ActionMenuItem[];
68
+ /** The button's name, for screen readers and the tooltip. */
69
+ label?: string;
70
+ className?: string;
71
+ /** The button's content in place of "⋯": the round look goes, `className` draws it. */
72
+ trigger?: ReactNode;
73
+ }
74
+ /** A "⋯" button that unfolds secondary actions above everything, never clipped by a scrolling parent. */
75
+ export const ActionMenu: ComponentType<ActionMenuProps>;
55
76
  export interface CopyButtonProps {
56
77
  value: string;
57
78
  /** What gets copied, for the tooltip and screen readers ("Copier la clé"). */
@@ -77,6 +98,30 @@ declare module 'deveye-sdk-client' {
77
98
  * `filter: opacity()`, never `opacity`.
78
99
  */
79
100
  export const LoadingVeil: ComponentType<LoadingVeilProps>;
101
+ export interface ProgressBarProps {
102
+ /** From 0 to 1 when the progress is measured; absent, the bar sweeps without promising anything. */
103
+ value?: number;
104
+ /** Read by screen readers. */
105
+ label: string;
106
+ className?: string;
107
+ }
108
+ export const ProgressBar: ComponentType<ProgressBarProps>;
109
+ export interface ProgressDialogProps {
110
+ open: boolean;
111
+ title: string;
112
+ /** What is being done, and why it is worth the wait. */
113
+ description?: string;
114
+ /** See {@link ProgressBarProps.value}. */
115
+ value?: number;
116
+ /** The current step, under the bar. */
117
+ step?: string;
118
+ }
119
+ /**
120
+ * A long operation under way: a dialog nothing closes while it lasts, and
121
+ * a bar. Its owner closes it (`open: false`) when the operation ends or
122
+ * gives up.
123
+ */
124
+ export const ProgressDialog: ComponentType<ProgressDialogProps>;
80
125
  export interface LogOutputProps {
81
126
  /** The raw log, ANSI sequences included: the component cleans it. */
82
127
  text: string;
@@ -164,15 +209,8 @@ declare module 'deveye-sdk-client' {
164
209
  /** Chips sharing a key exclude each other: activating one releases the others. */
165
210
  exclusive?: string;
166
211
  }
167
- /**
168
- * The app's dropdown. The search field (accent- and case-insensitive, group
169
- * names included) only appears from eight choices on, or on request; filter
170
- * chips can narrow the list. Safe inside a Dialog: the panel is portaled.
171
- */
172
- export function SearchSelect<T extends string>(props: {
173
- value: T;
212
+ interface SearchSelectCommonProps<T extends string> {
174
213
  options: readonly SearchSelectOption<T>[];
175
- onChange: (value: T) => void;
176
214
  'aria-label': string;
177
215
  /** What the trigger shows when no option carries the current value. */
178
216
  placeholder?: string;
@@ -188,7 +226,28 @@ declare module 'deveye-sdk-client' {
188
226
  autoFocus?: boolean;
189
227
  disabled?: boolean;
190
228
  className?: string;
191
- }): ReactNode;
229
+ }
230
+ /**
231
+ * The app's dropdown. The search field (accent- and case-insensitive, group
232
+ * names included) only appears from eight choices on, or on request; filter
233
+ * chips can narrow the list. Safe inside a Dialog: the panel is portaled.
234
+ * With `multiple`, each option is a check box: picking one toggles it and
235
+ * keeps the panel open.
236
+ */
237
+ export function SearchSelect<T extends string>(
238
+ props: SearchSelectCommonProps<T> & {
239
+ multiple?: false;
240
+ value: T;
241
+ onChange: (value: T) => void;
242
+ }
243
+ ): ReactNode;
244
+ export function SearchSelect<T extends string>(
245
+ props: SearchSelectCommonProps<T> & {
246
+ multiple: true;
247
+ value: readonly T[];
248
+ onChange: (value: T[]) => void;
249
+ }
250
+ ): ReactNode;
192
251
  /**
193
252
  * A labelled range input. `valueLabel` is how the value reads ("24", "80 %");
194
253
  * `marks` sit under the track; `indicator` draws a discreet tick at a
@@ -406,6 +465,15 @@ declare module 'deveye-sdk-client' {
406
465
  itemId: string;
407
466
  itemLabel: string;
408
467
  shareable?: boolean;
468
+ }
469
+ | {
470
+ /** A record (`manifest.settings.record`): a row with its own sheet that is not an item. */
471
+ kind: 'record';
472
+ feature: FeatureId;
473
+ recordId: string;
474
+ recordLabel: string;
475
+ /** The sentence under the title: what these settings act on. */
476
+ description: string;
409
477
  };
410
478
  /**
411
479
  * `link` renders an underlined word instead of a button, for the gesture
@@ -663,6 +731,22 @@ declare module 'deveye-sdk-client' {
663
731
  readonly code: string;
664
732
  readonly details?: unknown;
665
733
  }
734
+ export interface SendOptions {
735
+ /**
736
+ * How long the command may stay silent, 15 s by default: stretch it for
737
+ * a command that queries a slow third party. With `onProgress`, each
738
+ * update restarts the count.
739
+ */
740
+ timeoutMs?: number;
741
+ /** The updates the handler reports through `ctx.progress`, as they arrive. */
742
+ onProgress?: (update: Omit<RequestProgress, 'requestId'>) => void;
743
+ /**
744
+ * Run the command in another workspace of this instance (one of
745
+ * `useWorkspaces()`) instead of the active one: copying a record
746
+ * across. The server checks membership and rights there as usual.
747
+ */
748
+ workspaceId?: number;
749
+ }
666
750
  /**
667
751
  * The typed sender of any list of contracts (`featureApi` is it on a
668
752
  * manifest's commands). `commandsApi(agentCommands)` is how a module talks
@@ -677,7 +761,7 @@ declare module 'deveye-sdk-client' {
677
761
  send<N extends C[number]['command']>(
678
762
  name: N,
679
763
  input: z.input<Extract<C[number], { command: N }>['input'] & ZodType>,
680
- opts?: { timeoutMs?: number }
764
+ opts?: SendOptions
681
765
  ): Promise<z.output<Extract<C[number], { command: N }>['output'] & ZodType>>;
682
766
  };
683
767
  export function featureApi<const M extends FeatureManifest>(
@@ -686,8 +770,7 @@ declare module 'deveye-sdk-client' {
686
770
  send<N extends M['commands'][number]['command']>(
687
771
  name: N,
688
772
  input: z.input<Extract<M['commands'][number], { command: N }>['input'] & ZodType>,
689
- /** `timeoutMs` stretches the wait for a command that queries a slow third party. */
690
- opts?: { timeoutMs?: number }
773
+ opts?: SendOptions
691
774
  ): Promise<z.output<Extract<M['commands'][number], { command: N }>['output'] & ZodType>>;
692
775
  };
693
776
 
@@ -945,6 +1028,17 @@ declare module 'deveye-sdk-client' {
945
1028
  export function useFeatureLifecycle(hooks: { onUnmount?: () => void }): void;
946
1029
  /** The members of the active workspace, as the session lists them (empty before it answers). */
947
1030
  export function useWorkspaceMembers(): readonly MinimalUser[];
1031
+ /**
1032
+ * The caller's workspaces on this instance, the active one included, with
1033
+ * the features each has on. A target for `SendOptions.workspaceId`; the
1034
+ * rights there are the server's to judge.
1035
+ */
1036
+ export function useWorkspaces(): ReadonlyArray<{
1037
+ id: number;
1038
+ kind: 'personal' | 'shared';
1039
+ name: string;
1040
+ features: readonly string[];
1041
+ }>;
948
1042
  /**
949
1043
  * The domains of a feature whose manifest declares `domains`, in the
950
1044
  * active workspace, kept live. For a form that designates one (filter on
package/src/sdk/client.ts CHANGED
@@ -13,10 +13,14 @@ import type { ComponentType, ReactNode } from 'react';
13
13
  /**
14
14
  * The scope a settings panel is opened for. An item id is text, whatever key
15
15
  * the feature's own table uses: a row-keyed feature reads it back with
16
- * `Number(...)`, a device is a UUID as it stands.
16
+ * `Number(...)`, a device is a UUID as it stands. A `record` is a row the
17
+ * feature opens on its own sheet without it being an item (an invoice, whose
18
+ * client is the item): its tabs are `manifest.settings.record`.
17
19
  */
18
20
  export type SdkSettingsScope =
19
- { kind: 'feature' } | { kind: 'item'; itemId: string; itemLabel: string };
21
+ | { kind: 'feature' }
22
+ | { kind: 'item'; itemId: string; itemLabel: string }
23
+ | { kind: 'record'; recordId: string; recordLabel: string };
20
24
 
21
25
  export interface SettingsPanelProps {
22
26
  scope: SdkSettingsScope;
@@ -95,7 +99,8 @@ export interface FeatureClient {
95
99
  * The compact topbar widget declared by `manifest.topbarWidget`. Rendered
96
100
  * with NO props: everything it shows must come through YOUR feature's
97
101
  * commands, which the server authorizes against the caller's grants. The
98
- * host mounts it only for members whose role grants your feature.
102
+ * host mounts it only for members whose role grants your feature, inside
103
+ * a button that opens your feature: put nothing interactive in it.
99
104
  */
100
105
  TopbarWidget?: ComponentType;
101
106
  /**
@@ -379,11 +384,14 @@ export interface GitClientProvider {
379
384
  * sync progress, and renders the host's "unlink" as its trailing action.
380
385
  */
381
386
  LinkedRepo: ComponentType<{ repoId: number; canWrite: boolean; onUnlink: () => void }>;
382
- /** The feature's repository form, to declare a new repository from a project. */
387
+ /**
388
+ * The feature's repository form, to declare new repositories from a
389
+ * project. Several can be checked at once: `onSaved` receives every id added.
390
+ */
383
391
  RepoDialog: ComponentType<{
384
392
  open: boolean;
385
393
  onClose: () => void;
386
- onSaved: (repoId: number) => void;
394
+ onSaved: (repoIds: readonly number[]) => void;
387
395
  }>;
388
396
  }
389
397
 
package/src/sdk/ids.ts CHANGED
@@ -2,7 +2,7 @@
2
2
  * Feature ids, re-exported for SDK consumers.
3
3
  *
4
4
  * DevEye has two id families sharing one namespace:
5
- * - the sixteen **native** feature ids, a closed enum (`WorkspaceFeatureId`);
5
+ * - the **native** feature ids, a closed enum (`WorkspaceFeatureId`);
6
6
  * - **external** module ids, `x-<slug>` strings matching
7
7
  * {@link EXTERNAL_FEATURE_ID_PATTERN}.
8
8
  *
@@ -143,6 +143,27 @@ test('validateManifest refuses a tab id it does not know', () => {
143
143
  );
144
144
  });
145
145
 
146
+ test('validateManifest keeps record settings to general and custom tabs', () => {
147
+ assert.doesNotThrow(() =>
148
+ validateManifest({
149
+ ...base,
150
+ settings: { record: ['general', { id: 'copy', label: 'Copy' }] }
151
+ })
152
+ );
153
+ assert.throws(
154
+ () => validateManifest({ ...base, settings: { record: ['notifications' as 'general'] } }),
155
+ /record settings take general and custom tabs/
156
+ );
157
+ assert.throws(
158
+ () =>
159
+ validateManifest({
160
+ ...base,
161
+ settings: { record: [{ id: 'sharing', label: 'Share' }] }
162
+ }),
163
+ /invalid custom tab id/
164
+ );
165
+ });
166
+
146
167
  test('validateManifest checks quotas and the account entry', () => {
147
168
  const rejects = (patch: Partial<FeatureManifest>, fragment: string) =>
148
169
  assert.throws(() => validateManifest({ ...base, ...patch }), new RegExp(fragment));
@@ -345,7 +345,15 @@ export interface FeatureManifest<Id extends FeatureId = FeatureId> {
345
345
  * a sign-up that carried a hint (`/signup?plan=…`), and receives it. One
346
346
  * installed module at most may ask for it.
347
347
  */
348
- accountEntry?: { label: string; signupHint?: boolean };
348
+ accountEntry?: {
349
+ label: string;
350
+ signupHint?: boolean;
351
+ /**
352
+ * The view also holds tools for global administrators (other accounts,
353
+ * site-wide figures): the menu marks the entry for them, and only them.
354
+ */
355
+ adminTools?: boolean;
356
+ };
349
357
  /**
350
358
  * A page of yours among the system pages of the account menu, which only a
351
359
  * global administrator sees and opens: what the operator of the instance
@@ -402,6 +410,13 @@ export interface FeatureManifest<Id extends FeatureId = FeatureId> {
402
410
  settings?: {
403
411
  feature?: readonly (SettingsTab | CustomTabRef)[];
404
412
  item?: readonly (SettingsTab | CustomTabRef)[];
413
+ /**
414
+ * The tabs of a record: a row your view opens on its own sheet without
415
+ * it being an item (an invoice, whose client is the item). Mounted with
416
+ * `FeatureSettingsButton` on a `record` scope; `general` and custom tabs
417
+ * only, since sharing, permissions and notifications belong to items.
418
+ */
419
+ record?: readonly ('general' | CustomTabRef)[];
405
420
  };
406
421
 
407
422
  commands: readonly ManifestCommand[];
@@ -582,6 +597,15 @@ export function validateManifest(m: FeatureManifest): void {
582
597
  fail(m.id, 'item settings require hasItems');
583
598
  }
584
599
  }
600
+ for (const tab of m.settings?.record ?? []) {
601
+ if (typeof tab === 'string') {
602
+ if (tab !== 'general') {
603
+ fail(m.id, `record settings take general and custom tabs, not « ${String(tab)} »`);
604
+ }
605
+ } else if (!CUSTOM_TAB_PATTERN.test(tab.id) || BUILTIN_TABS.includes(tab.id)) {
606
+ fail(m.id, `invalid custom tab id « ${tab.id} »`);
607
+ }
608
+ }
585
609
  }
586
610
 
587
611
  /**
@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
2
2
  import { createServer, type Server } from 'node:http';
3
3
  import test from 'node:test';
4
4
 
5
- import { isPublicIp, isSafePublicUrl, NetRefused, safeFetchText } from './net';
5
+ import { isPublicIp, isRemoteFailure, isSafePublicUrl, NetRefused, safeFetchText } from './net';
6
6
 
7
7
  test('isPublicIp: the private ranges of both families read as false', () => {
8
8
  for (const ip of ['8.8.8.8', '1.1.1.1', '2001:4860:4860::8888']) {
@@ -90,3 +90,22 @@ test('safeFetchText: other schemes, names that do not resolve and private IPs ar
90
90
  await assert.rejects(safeFetchText(url, OPTIONS), NetRefused, url);
91
91
  }
92
92
  });
93
+
94
+ test('isRemoteFailure: the far end is to blame, down the cause chain', () => {
95
+ const socket = (code: string) => Object.assign(new Error(code), { code });
96
+ assert.equal(isRemoteFailure(socket('ECONNREFUSED')), true);
97
+ assert.equal(
98
+ isRemoteFailure(new TypeError('fetch failed', { cause: socket('ENOTFOUND') })),
99
+ true
100
+ );
101
+ assert.equal(isRemoteFailure(new DOMException('timed out', 'TimeoutError')), true);
102
+ assert.equal(isRemoteFailure(new NetRefused('Réponse 404')), true);
103
+ });
104
+
105
+ test('isRemoteFailure: anything unexplained stays the instance’s', () => {
106
+ assert.equal(isRemoteFailure(new Error('boom')), false);
107
+ assert.equal(isRemoteFailure(Object.assign(new Error('dns'), { code: 'EAI_AGAIN' })), false);
108
+ assert.equal(isRemoteFailure(new DOMException('aborted', 'AbortError')), false);
109
+ assert.equal(isRemoteFailure('ECONNREFUSED'), false);
110
+ assert.equal(isRemoteFailure(null), false);
111
+ });
package/src/sdk/net.ts CHANGED
@@ -82,6 +82,55 @@ const MAX_REDIRECTS = 3;
82
82
  /** What `safeFetchText` throws for anything it refuses, its message readable as is. */
83
83
  export class NetRefused extends Error {}
84
84
 
85
+ /** Socket and TLS codes that put the fault at the far end of a connection. */
86
+ const REMOTE_FAILURE_CODES = new Set([
87
+ 'ENOTFOUND',
88
+ 'ENODATA',
89
+ 'ECONNREFUSED',
90
+ 'ECONNRESET',
91
+ 'ECONNABORTED',
92
+ 'ETIMEDOUT',
93
+ 'ESOCKETTIMEDOUT',
94
+ 'EHOSTUNREACH',
95
+ 'EPIPE',
96
+ 'ERR_STREAM_PREMATURE_CLOSE',
97
+ 'UND_ERR_CONNECT_TIMEOUT',
98
+ 'UND_ERR_HEADERS_TIMEOUT',
99
+ 'UND_ERR_BODY_TIMEOUT',
100
+ 'UND_ERR_SOCKET',
101
+ 'CERT_HAS_EXPIRED',
102
+ 'CERT_NOT_YET_VALID',
103
+ 'DEPTH_ZERO_SELF_SIGNED_CERT',
104
+ 'SELF_SIGNED_CERT_IN_CHAIN',
105
+ 'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
106
+ 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
107
+ 'ERR_TLS_CERT_ALTNAME_INVALID'
108
+ ]);
109
+
110
+ /**
111
+ * Did this failure come from the other end: a name that does not resolve, a
112
+ * connection refused, reset or left silent, a certificate that does not hold,
113
+ * a peer that hung up mid-transfer, or a {@link NetRefused} refusal? Walks the
114
+ * `cause` chain, where `fetch` hides the socket error. A resolver that answers
115
+ * nothing (`EAI_AGAIN`) or a network the instance cannot reach stays the
116
+ * instance's, as does anything unrecognised.
117
+ */
118
+ export function isRemoteFailure(error: unknown): boolean {
119
+ let current: unknown = error;
120
+ for (let depth = 0; depth < 5 && typeof current === 'object' && current !== null; depth += 1) {
121
+ if (current instanceof NetRefused) return true;
122
+ const { name, code, cause } = current as {
123
+ name?: unknown;
124
+ code?: unknown;
125
+ cause?: unknown;
126
+ };
127
+ if (name === 'TimeoutError') return true;
128
+ if (typeof code === 'string' && REMOTE_FAILURE_CODES.has(code)) return true;
129
+ current = cause;
130
+ }
131
+ return false;
132
+ }
133
+
85
134
  /** Do all the addresses of a name read as public? A name without any address is refused. */
86
135
  export async function resolvesPublicly(host: string): Promise<boolean> {
87
136
  const bare = host.replace(/^\[|\]$/g, '');
package/src/sdk/server.ts CHANGED
@@ -15,6 +15,7 @@ import type { UserColor } from '../domain/user';
15
15
  import type { SdkDnsRecord } from './domains';
16
16
  import type { MailTransportMessage } from './providers';
17
17
  import type { ModuleEnvSpec } from './env';
18
+ import type { ExternalService } from '../domain/externalService';
18
19
  import type {
19
20
  AgentSyncAckPayload,
20
21
  AgentSyncApplyChunkPayload,
@@ -42,6 +43,7 @@ import type {
42
43
 
43
44
  export {
44
45
  isPublicIp,
46
+ isRemoteFailure,
45
47
  isSafePublicUrl,
46
48
  NetRefused,
47
49
  resolvesPublicly,
@@ -88,7 +90,15 @@ export {
88
90
  * native features only through the declared {@link DevEyeFacade}.
89
91
  */
90
92
 
91
- /** Structural subset of the app logger (pino-compatible). */
93
+ /**
94
+ * Structural subset of the app logger (pino-compatible).
95
+ *
96
+ * `warn` and `error` are the operator's ladder: a bug, the instance's own
97
+ * configuration, a dependency of the instance. A failure a user's own side
98
+ * explains (their host unreachable, their credentials revoked, their agent
99
+ * outdated, a quota of theirs reached) goes out as `info` with the field
100
+ * `cause: 'user'`, see {@link logFailure}.
101
+ */
92
102
  export interface SdkLogger {
93
103
  debug(obj: unknown, msg?: string): void;
94
104
  info(obj: unknown, msg?: string): void;
@@ -96,6 +106,24 @@ export interface SdkLogger {
96
106
  error(obj: unknown, msg?: string): void;
97
107
  }
98
108
 
109
+ /**
110
+ * Logs a failure at the level its cause calls for. `userSide`: the user's own
111
+ * side explains it, and the line goes out as `info` tagged `cause: 'user'`, off
112
+ * the operator's ladder yet still searchable, so a wave of them across accounts
113
+ * still shows. Otherwise it stays at `level`. A failure nobody has explained is
114
+ * the instance's: pass `false`.
115
+ */
116
+ export function logFailure(
117
+ logger: SdkLogger,
118
+ userSide: boolean,
119
+ fields: Record<string, unknown>,
120
+ msg: string,
121
+ level: 'warn' | 'error' = 'warn'
122
+ ): void {
123
+ if (userSide) logger.info({ ...fields, cause: 'user' }, msg);
124
+ else logger[level](fields, msg);
125
+ }
126
+
99
127
  /**
100
128
  * The typed error a handler throws to reply with a clean protocol error.
101
129
  * Anything else becomes an opaque `internal` error. Codes you will use:
@@ -112,6 +140,13 @@ export class FeatureError extends Error {
112
140
  }
113
141
  }
114
142
 
143
+ /** One update of {@link SdkFeatureContext.progress}: what is known, the rest left out. */
144
+ export interface CommandProgress {
145
+ done?: number;
146
+ total?: number;
147
+ step?: string;
148
+ }
149
+
115
150
  /**
116
151
  * A cipher over strings. `decrypt` throws a {@link FeatureError} (`locked`
117
152
  * when the guarded tier is sealed, `forbidden` for a foreign caller);
@@ -1160,6 +1195,13 @@ export interface SdkFeatureContext<Repo = unknown> {
1160
1195
  }): void;
1161
1196
  logger: SdkLogger;
1162
1197
  requestId: string;
1198
+ /**
1199
+ * Report how far this command has got, to its caller only. Best effort, at
1200
+ * most 4 frames a second (the last one always goes out); each frame re-arms
1201
+ * the caller's timeout, so a long command that keeps reporting never times
1202
+ * out. Steps are user-facing sentences.
1203
+ */
1204
+ progress(update: CommandProgress): void;
1163
1205
  /** The server key derivations, the same `keys` a service gets. */
1164
1206
  keys: SdkServerKeys;
1165
1207
  /** The push lane, in this workspace (capability `'live.publish'`). */
@@ -1566,6 +1608,17 @@ export interface FeatureServer<Repo = unknown> {
1566
1608
  * warns about every variable left to its default.
1567
1609
  */
1568
1610
  env?: ModuleEnvSpec;
1611
+ /**
1612
+ * The external services you depend on at the instance level (a provider
1613
+ * reached with the instance's own key), and their state: shown on the
1614
+ * administrator's "Services externes" page each time it is opened or
1615
+ * refreshed. Network calls are allowed; the host gives up after 8 s and
1616
+ * shows them as not answering. Cache what is costly to read. Never a
1617
+ * service a workspace sets up itself.
1618
+ */
1619
+ externalServices?(
1620
+ ctx: SdkExternalServicesContext<Repo>
1621
+ ): Promise<readonly SdkExternalService[]>;
1569
1622
  /**
1570
1623
  * Every email you send, on made-up data, for the administrator's mail
1571
1624
  * tester: built by the SAME function as the real one, or the tester proves
@@ -1577,6 +1630,16 @@ export interface FeatureServer<Repo = unknown> {
1577
1630
  e2e?: FeatureE2eEntry<Repo>;
1578
1631
  }
1579
1632
 
1633
+ /** What `FeatureServer.externalServices` is called with. */
1634
+ export interface SdkExternalServicesContext<Repo = unknown> {
1635
+ repo: Repo;
1636
+ /** The administrator asked to check again: skip your cache. */
1637
+ refresh: boolean;
1638
+ }
1639
+
1640
+ /** One card of the "Services externes" page. */
1641
+ export type SdkExternalService = ExternalService;
1642
+
1580
1643
  /** What a mail sample is built with. */
1581
1644
  export interface SdkMailSampleContext {
1582
1645
  origins: SdkOrigins;
@@ -12,6 +12,7 @@ import {
12
12
  FeatureError,
13
13
  type AgentFolderArchive,
14
14
  type AgentFolderArchiveSummary,
15
+ type CommandProgress,
15
16
  type DevEyeFacade,
16
17
  type FeatureDomainsContext,
17
18
  type FeatureServer,
@@ -143,6 +144,12 @@ export interface RecordedCalls {
143
144
  accountChanges: number[];
144
145
  }
145
146
 
147
+ /** What a command's test context records on top of {@link RecordedCalls}. */
148
+ export interface RecordedContextCalls extends RecordedCalls {
149
+ /** Updates reported through `progress`, in order. */
150
+ progress: CommandProgress[];
151
+ }
152
+
146
153
  function recordingNotify(
147
154
  recorded: RecordedCalls,
148
155
  hasRoute: boolean,
@@ -430,7 +437,7 @@ function fakeProviders(table: Readonly<Record<string, unknown>>): SdkProviders {
430
437
  }
431
438
 
432
439
  export interface TestContext<Repo> extends SdkFeatureContext<Repo> {
433
- recorded: RecordedCalls;
440
+ recorded: RecordedContextCalls;
434
441
  store: TestFeatureStore;
435
442
  /** Item ids passed to `items.forget`, in order. */
436
443
  forgotten: string[];
@@ -525,7 +532,7 @@ export interface TestContextOverrides<Repo> {
525
532
  export function createTestContext<Repo = undefined>(
526
533
  overrides: TestContextOverrides<Repo> = {}
527
534
  ): TestContext<Repo> {
528
- const recorded: RecordedCalls = {
535
+ const recorded: RecordedContextCalls = {
529
536
  notifications: [],
530
537
  liveMessages: [],
531
538
  audits: [],
@@ -533,7 +540,8 @@ export function createTestContext<Repo = undefined>(
533
540
  archiveRequests: [],
534
541
  pinnedInstants: [],
535
542
  livePublishes: [],
536
- accountChanges: []
543
+ accountChanges: [],
544
+ progress: []
537
545
  };
538
546
  const isOwner = overrides.isOwner ?? true;
539
547
  const workspaceId = overrides.workspaceId ?? 1;
@@ -730,6 +738,9 @@ export function createTestContext<Repo = undefined>(
730
738
  },
731
739
  logger: silentLogger,
732
740
  requestId: 'test',
741
+ progress: (update) => {
742
+ recorded.progress.push(update);
743
+ },
733
744
  origins: overrides.origins ?? {
734
745
  app: 'https://deveye.test',
735
746
  public: 'https://public.deveye.test',