@deveye/types 0.23.0 → 0.24.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deveye/types",
3
- "version": "0.23.0",
3
+ "version": "0.24.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,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>;
@@ -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,
@@ -899,6 +921,8 @@ export type {
899
921
  export {
900
922
  adminCommands,
901
923
  adminDeleteUser,
924
+ adminExternalServices,
925
+ adminExternalServicesSchema,
902
926
  adminMaintenanceDismissNotice,
903
927
  adminMaintenanceFeature,
904
928
  adminMaintenanceGet,
@@ -912,7 +936,7 @@ export {
912
936
  adminUserList,
913
937
  adminUserSchema
914
938
  } from './features/admin';
915
- export type { AdminMaintenance, AdminUser } from './features/admin';
939
+ export type { AdminExternalServices, AdminMaintenance, AdminUser } from './features/admin';
916
940
  export {
917
941
  debugBenchCatalog,
918
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
@@ -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';
@@ -16,7 +16,8 @@ declare module 'deveye-sdk-client' {
16
16
  DragEvent,
17
17
  InputHTMLAttributes,
18
18
  ReactNode,
19
- RefObject
19
+ RefObject,
20
+ TextareaHTMLAttributes
20
21
  } from 'react';
21
22
  import type { z, ZodType } from 'zod';
22
23
  import type {
@@ -29,6 +30,7 @@ declare module 'deveye-sdk-client' {
29
30
  FeatureId,
30
31
  MinimalUser,
31
32
  PathExclusionKind,
33
+ RequestProgress,
32
34
  User,
33
35
  WorkspaceCapability
34
36
  } from '@deveye/types';
@@ -50,7 +52,23 @@ declare module 'deveye-sdk-client' {
50
52
  }
51
53
  >;
52
54
  export const TextInput: ComponentType<
53
- InputHTMLAttributes<HTMLInputElement> & { enableShowHideButton?: boolean; error?: string }
55
+ InputHTMLAttributes<HTMLInputElement> & {
56
+ enableShowHideButton?: boolean;
57
+ error?: string;
58
+ /**
59
+ * Shows a clear button inside the field while it holds a value. On a date or time
60
+ * field it shows on touch screens only: desktop browsers draw their own.
61
+ */
62
+ onClear?: () => void;
63
+ }
64
+ >;
65
+ /** A multi-line field with the look of `TextInput`. */
66
+ export const TextArea: ComponentType<
67
+ TextareaHTMLAttributes<HTMLTextAreaElement> & {
68
+ /** The height follows the content from one line on, with no manual resize. */
69
+ autoGrow?: boolean;
70
+ error?: string;
71
+ }
54
72
  >;
55
73
  export interface ActionMenuItem {
56
74
  label: string;
@@ -97,6 +115,30 @@ declare module 'deveye-sdk-client' {
97
115
  * `filter: opacity()`, never `opacity`.
98
116
  */
99
117
  export const LoadingVeil: ComponentType<LoadingVeilProps>;
118
+ export interface ProgressBarProps {
119
+ /** From 0 to 1 when the progress is measured; absent, the bar sweeps without promising anything. */
120
+ value?: number;
121
+ /** Read by screen readers. */
122
+ label: string;
123
+ className?: string;
124
+ }
125
+ export const ProgressBar: ComponentType<ProgressBarProps>;
126
+ export interface ProgressDialogProps {
127
+ open: boolean;
128
+ title: string;
129
+ /** What is being done, and why it is worth the wait. */
130
+ description?: string;
131
+ /** See {@link ProgressBarProps.value}. */
132
+ value?: number;
133
+ /** The current step, under the bar. */
134
+ step?: string;
135
+ }
136
+ /**
137
+ * A long operation under way: a dialog nothing closes while it lasts, and
138
+ * a bar. Its owner closes it (`open: false`) when the operation ends or
139
+ * gives up.
140
+ */
141
+ export const ProgressDialog: ComponentType<ProgressDialogProps>;
100
142
  export interface LogOutputProps {
101
143
  /** The raw log, ANSI sequences included: the component cleans it. */
102
144
  text: string;
@@ -440,6 +482,15 @@ declare module 'deveye-sdk-client' {
440
482
  itemId: string;
441
483
  itemLabel: string;
442
484
  shareable?: boolean;
485
+ }
486
+ | {
487
+ /** A record (`manifest.settings.record`): a row with its own sheet that is not an item. */
488
+ kind: 'record';
489
+ feature: FeatureId;
490
+ recordId: string;
491
+ recordLabel: string;
492
+ /** The sentence under the title: what these settings act on. */
493
+ description: string;
443
494
  };
444
495
  /**
445
496
  * `link` renders an underlined word instead of a button, for the gesture
@@ -697,6 +748,22 @@ declare module 'deveye-sdk-client' {
697
748
  readonly code: string;
698
749
  readonly details?: unknown;
699
750
  }
751
+ export interface SendOptions {
752
+ /**
753
+ * How long the command may stay silent, 15 s by default: stretch it for
754
+ * a command that queries a slow third party. With `onProgress`, each
755
+ * update restarts the count.
756
+ */
757
+ timeoutMs?: number;
758
+ /** The updates the handler reports through `ctx.progress`, as they arrive. */
759
+ onProgress?: (update: Omit<RequestProgress, 'requestId'>) => void;
760
+ /**
761
+ * Run the command in another workspace of this instance (one of
762
+ * `useWorkspaces()`) instead of the active one: copying a record
763
+ * across. The server checks membership and rights there as usual.
764
+ */
765
+ workspaceId?: number;
766
+ }
700
767
  /**
701
768
  * The typed sender of any list of contracts (`featureApi` is it on a
702
769
  * manifest's commands). `commandsApi(agentCommands)` is how a module talks
@@ -711,7 +778,7 @@ declare module 'deveye-sdk-client' {
711
778
  send<N extends C[number]['command']>(
712
779
  name: N,
713
780
  input: z.input<Extract<C[number], { command: N }>['input'] & ZodType>,
714
- opts?: { timeoutMs?: number }
781
+ opts?: SendOptions
715
782
  ): Promise<z.output<Extract<C[number], { command: N }>['output'] & ZodType>>;
716
783
  };
717
784
  export function featureApi<const M extends FeatureManifest>(
@@ -720,8 +787,7 @@ declare module 'deveye-sdk-client' {
720
787
  send<N extends M['commands'][number]['command']>(
721
788
  name: N,
722
789
  input: z.input<Extract<M['commands'][number], { command: N }>['input'] & ZodType>,
723
- /** `timeoutMs` stretches the wait for a command that queries a slow third party. */
724
- opts?: { timeoutMs?: number }
790
+ opts?: SendOptions
725
791
  ): Promise<z.output<Extract<M['commands'][number], { command: N }>['output'] & ZodType>>;
726
792
  };
727
793
 
@@ -979,6 +1045,17 @@ declare module 'deveye-sdk-client' {
979
1045
  export function useFeatureLifecycle(hooks: { onUnmount?: () => void }): void;
980
1046
  /** The members of the active workspace, as the session lists them (empty before it answers). */
981
1047
  export function useWorkspaceMembers(): readonly MinimalUser[];
1048
+ /**
1049
+ * The caller's workspaces on this instance, the active one included, with
1050
+ * the features each has on. A target for `SendOptions.workspaceId`; the
1051
+ * rights there are the server's to judge.
1052
+ */
1053
+ export function useWorkspaces(): ReadonlyArray<{
1054
+ id: number;
1055
+ kind: 'personal' | 'shared';
1056
+ name: string;
1057
+ features: readonly string[];
1058
+ }>;
982
1059
  /**
983
1060
  * The domains of a feature whose manifest declares `domains`, in the
984
1061
  * active workspace, kept live. For a form that designates one (filter on
@@ -1002,6 +1079,11 @@ declare module 'deveye-sdk-client' {
1002
1079
  }>;
1003
1080
  /** The CSS variable of an account colour, the one the live presence paints with. */
1004
1081
  export function userColorVar(color: MinimalUser['color']): string;
1082
+ /**
1083
+ * The theme on screen. Code that reads theme tokens from JS (a canvas, a
1084
+ * third-party library) depends on it to read them again when it changes.
1085
+ */
1086
+ export function useColorScheme(): 'dark' | 'light';
1005
1087
  /**
1006
1088
  * Two sticky bands, one under the other: measure the top one and hand the
1007
1089
  * ancestor a `--sticky-head` variable the lower band offsets itself by.
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;
@@ -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));
@@ -410,6 +410,13 @@ export interface FeatureManifest<Id extends FeatureId = FeatureId> {
410
410
  settings?: {
411
411
  feature?: readonly (SettingsTab | CustomTabRef)[];
412
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)[];
413
420
  };
414
421
 
415
422
  commands: readonly ManifestCommand[];
@@ -590,6 +597,15 @@ export function validateManifest(m: FeatureManifest): void {
590
597
  fail(m.id, 'item settings require hasItems');
591
598
  }
592
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
+ }
593
609
  }
594
610
 
595
611
  /**
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,
@@ -139,6 +140,13 @@ export class FeatureError extends Error {
139
140
  }
140
141
  }
141
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
+
142
150
  /**
143
151
  * A cipher over strings. `decrypt` throws a {@link FeatureError} (`locked`
144
152
  * when the guarded tier is sealed, `forbidden` for a foreign caller);
@@ -1187,6 +1195,13 @@ export interface SdkFeatureContext<Repo = unknown> {
1187
1195
  }): void;
1188
1196
  logger: SdkLogger;
1189
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;
1190
1205
  /** The server key derivations, the same `keys` a service gets. */
1191
1206
  keys: SdkServerKeys;
1192
1207
  /** The push lane, in this workspace (capability `'live.publish'`). */
@@ -1593,6 +1608,17 @@ export interface FeatureServer<Repo = unknown> {
1593
1608
  * warns about every variable left to its default.
1594
1609
  */
1595
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[]>;
1596
1622
  /**
1597
1623
  * Every email you send, on made-up data, for the administrator's mail
1598
1624
  * tester: built by the SAME function as the real one, or the tester proves
@@ -1604,6 +1630,16 @@ export interface FeatureServer<Repo = unknown> {
1604
1630
  e2e?: FeatureE2eEntry<Repo>;
1605
1631
  }
1606
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
+
1607
1643
  /** What a mail sample is built with. */
1608
1644
  export interface SdkMailSampleContext {
1609
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',