@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 +30 -21
- package/package.json +1 -1
- package/src/domain/externalService.ts +45 -0
- package/src/domain/home.ts +3 -2
- package/src/domain/report.ts +9 -3
- package/src/features/admin.ts +27 -1
- package/src/features/agent.ts +5 -3
- package/src/index.ts +28 -3
- package/src/protocol/agent.ts +14 -8
- package/src/protocol/envelope.ts +17 -0
- package/src/sdk/client-ambient.d.ts +106 -12
- package/src/sdk/client.ts +13 -5
- package/src/sdk/ids.ts +1 -1
- package/src/sdk/manifest.test.ts +21 -0
- package/src/sdk/manifest.ts +25 -1
- package/src/sdk/net.test.ts +20 -1
- package/src/sdk/net.ts +49 -0
- package/src/sdk/server.ts +64 -1
- package/src/sdk/testing.ts +14 -3
package/README.md
CHANGED
|
@@ -1,29 +1,38 @@
|
|
|
1
1
|
# @deveye/types
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
-
|
|
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
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
- **`@deveye/types/sdk/
|
|
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
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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
|
-
|
|
23
|
-
[template](https://github.com/Gerem66/DevEye-Feature-Template)
|
|
29
|
+
To write a module, start from the
|
|
30
|
+
[template](https://github.com/Gerem66/DevEye-Feature-Template) and its docs.
|
|
24
31
|
|
|
25
|
-
##
|
|
32
|
+
## License
|
|
26
33
|
|
|
27
|
-
[MIT](LICENSE).
|
|
28
|
-
|
|
29
|
-
|
|
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
|
@@ -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>;
|
package/src/domain/home.ts
CHANGED
|
@@ -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
|
|
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(
|
|
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
|
});
|
package/src/domain/report.ts
CHANGED
|
@@ -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
|
-
*
|
|
240
|
-
*
|
|
241
|
-
*
|
|
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
|
/**
|
package/src/features/admin.ts
CHANGED
|
@@ -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;
|
package/src/features/agent.ts
CHANGED
|
@@ -75,13 +75,15 @@ export const agentLifecycle = {
|
|
|
75
75
|
};
|
|
76
76
|
|
|
77
77
|
/**
|
|
78
|
-
*
|
|
79
|
-
* Pushes `agent.service`
|
|
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 {
|
|
2
|
-
|
|
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,
|
package/src/protocol/agent.ts
CHANGED
|
@@ -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
|
-
* - `
|
|
80
|
-
*
|
|
81
|
-
* - `
|
|
82
|
-
* - `
|
|
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
|
-
'
|
|
86
|
-
'
|
|
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(
|
|
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
|
|
package/src/protocol/envelope.ts
CHANGED
|
@@ -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
|
-
}
|
|
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?:
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
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: (
|
|
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
|
|
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
|
*
|
package/src/sdk/manifest.test.ts
CHANGED
|
@@ -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));
|
package/src/sdk/manifest.ts
CHANGED
|
@@ -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?: {
|
|
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
|
/**
|
package/src/sdk/net.test.ts
CHANGED
|
@@ -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
|
-
/**
|
|
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;
|
package/src/sdk/testing.ts
CHANGED
|
@@ -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:
|
|
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:
|
|
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',
|