@deveye/types 0.26.1 → 0.27.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.
@@ -122,6 +122,33 @@ export const agentPkgListResultPayloadSchema = z.object({
122
122
  * count. A tool whose probe fails still gets its frame (`null`), so the
123
123
  * screen never waits for a count that will not come.
124
124
  */
125
+ /**
126
+ * Reply to `pkg.inventory`: the packages installed on the host, for the CVE
127
+ * watch. `source` is the source package a Debian advisory names; `manager`
128
+ * is `null` when no supported database was found (`error` says why).
129
+ */
130
+ export const AGENT_PKG_INVENTORY_RESULT = 'pkg.inventoryResult' as const;
131
+ export const installedPackageSchema = z.object({
132
+ name: z.string().min(1).max(200),
133
+ version: z.string().min(1).max(200),
134
+ arch: z.string().max(40),
135
+ source: z.string().max(200).optional()
136
+ });
137
+ export type InstalledPackage = z.infer<typeof installedPackageSchema>;
138
+ export const packageInventorySchema = z.object({
139
+ /** `ID` and `VERSION_ID` of os-release. */
140
+ distroId: z.string().max(64).nullable(),
141
+ distroVersion: z.string().max(64).nullable(),
142
+ manager: z.enum(['dpkg', 'rpm', 'apk']).nullable(),
143
+ packages: z.array(installedPackageSchema).max(20_000),
144
+ error: z.string().max(500).nullable()
145
+ });
146
+ export type PackageInventory = z.infer<typeof packageInventorySchema>;
147
+ export const agentPkgInventoryResultPayloadSchema = z.object({
148
+ deviceId: z.uuid(),
149
+ inventory: packageInventorySchema
150
+ });
151
+
125
152
  export const AGENT_PKG_COUNT = 'pkg.count' as const;
126
153
 
127
154
  export const agentPkgCountPayloadSchema = z.object({
@@ -689,6 +716,10 @@ export const agentClientMessageSchema = z.discriminatedUnion('command', [
689
716
  command: z.literal(AGENT_DOCKER_INVENTORY_RESULT),
690
717
  payload: agentDockerInventoryResultPayloadSchema
691
718
  }),
719
+ z.object({
720
+ command: z.literal(AGENT_PKG_INVENTORY_RESULT),
721
+ payload: agentPkgInventoryResultPayloadSchema
722
+ }),
692
723
  z.object({
693
724
  command: z.literal(AGENT_DOCKER_STATS_RESULT),
694
725
  payload: agentDockerStatsResultPayloadSchema
@@ -885,6 +916,10 @@ export type AgentPkgUpgradePayload = z.infer<typeof agentPkgUpgradePayloadSchema
885
916
 
886
917
  /** Ask the agent for its container inventory (`docker.inventoryResult`). */
887
918
  export const AGENT_DOCKER_INVENTORY = 'docker.inventory' as const;
919
+ /** List the installed system packages (replies `pkg.inventoryResult`). Read-only, unsigned. */
920
+ export const AGENT_PKG_INVENTORY = 'pkg.inventory' as const;
921
+ /** What an agent that knows `pkg.inventory` declares in `report.agent.probes`. */
922
+ export const AGENT_PKG_INVENTORY_PROBE = 'pkgInventory';
888
923
 
889
924
  /** Ask the agent for a one-shot resource sample of the running containers. */
890
925
  export const AGENT_DOCKER_STATS = 'docker.stats' as const;
@@ -1433,6 +1468,10 @@ export const agentServerMessageSchema = z.discriminatedUnion('command', [
1433
1468
  command: z.literal(AGENT_DOCKER_INVENTORY),
1434
1469
  payload: z.object({})
1435
1470
  }),
1471
+ z.object({
1472
+ command: z.literal(AGENT_PKG_INVENTORY),
1473
+ payload: z.object({})
1474
+ }),
1436
1475
  z.object({
1437
1476
  command: z.literal(AGENT_DOCKER_STATS),
1438
1477
  payload: z.object({})
@@ -0,0 +1,44 @@
1
+ import assert from 'node:assert/strict';
2
+ import { describe, it } from 'node:test';
3
+
4
+ import { clientMessageSchema, commandTaskSchema, TASK_TITLE_MAX } from './envelope';
5
+
6
+ const ID = '0b6f5e0a-2a57-4a55-9a56-0d7c1d2a3b4c';
7
+
8
+ describe('commandTaskSchema', () => {
9
+ it('accepts the label a client sends with a long command', () => {
10
+ const tag = commandTaskSchema.parse({
11
+ id: ID,
12
+ title: ' Suppression du partage ',
13
+ subject: 'Documents',
14
+ feature: 'cloudsync',
15
+ itemId: '12',
16
+ key: 'share.delete',
17
+ done: 'Partage supprimé.',
18
+ failed: 'Suppression impossible.'
19
+ });
20
+ assert.equal(tag.title, 'Suppression du partage');
21
+ });
22
+
23
+ it('refuses an id that is not one, an empty title and a title too long', () => {
24
+ assert.equal(commandTaskSchema.safeParse({ id: 'short', title: 'x' }).success, false);
25
+ assert.equal(commandTaskSchema.safeParse({ id: `${ID}/../x`, title: 'x' }).success, false);
26
+ assert.equal(commandTaskSchema.safeParse({ id: ID, title: ' ' }).success, false);
27
+ assert.equal(
28
+ commandTaskSchema.safeParse({ id: ID, title: 'x'.repeat(TASK_TITLE_MAX + 1) }).success,
29
+ false
30
+ );
31
+ });
32
+ });
33
+
34
+ describe('clientMessageSchema', () => {
35
+ it('carries the task tag beside the workspace, and stays valid without it', () => {
36
+ const base = { requestId: 'r-1', command: 'cloudSync.deleteShare', payload: {} };
37
+ assert.equal(clientMessageSchema.parse(base).task, undefined);
38
+ assert.equal(
39
+ clientMessageSchema.parse({ ...base, task: { id: ID, title: 'Suppression' } }).task?.id,
40
+ ID
41
+ );
42
+ assert.equal(clientMessageSchema.safeParse({ ...base, task: { id: ID } }).success, false);
43
+ });
44
+ });
@@ -10,6 +10,40 @@ import { ProtocolErrorSchema } from './error';
10
10
  * unsolicited events with no `requestId`.
11
11
  */
12
12
 
13
+ export const TASK_TITLE_MAX = 120;
14
+ export const TASK_TEXT_MAX = 300;
15
+
16
+ /** The id of a long operation: chosen by the client that starts it, shown to the whole account. */
17
+ export const taskIdSchema = z
18
+ .string()
19
+ .min(8)
20
+ .max(64)
21
+ .regex(/^[A-Za-z0-9-]+$/);
22
+
23
+ /**
24
+ * What marks a command as a long operation the server follows (`domain/task`):
25
+ * its answer is kept for a while and its progress is shown to the caller's
26
+ * other tabs. The labels are the caller's: the interface sentences live in the
27
+ * client, and they only ever go back to the account that sent them. The id is
28
+ * not the `requestId`: the id is broadcast, the `requestId` never is, and
29
+ * claiming the kept answer takes both.
30
+ */
31
+ export const commandTaskSchema = z.object({
32
+ id: taskIdSchema,
33
+ title: z.string().trim().min(1).max(TASK_TITLE_MAX),
34
+ /** What it acts on, to tell two operations with the same title apart. */
35
+ subject: z.string().trim().min(1).max(TASK_TEXT_MAX).optional(),
36
+ feature: z.string().min(1).max(64).optional(),
37
+ itemId: z.string().min(1).max(64).optional(),
38
+ /** The kind of operation, as the screens of the feature filter on it. */
39
+ key: z.string().min(1).max(64).optional(),
40
+ /** The sentence of a success and the fallback sentence of a failure, for a tab that did not start it. */
41
+ done: z.string().trim().min(1).max(TASK_TEXT_MAX).optional(),
42
+ failed: z.string().trim().min(1).max(TASK_TEXT_MAX).optional()
43
+ });
44
+
45
+ export type CommandTask = z.infer<typeof commandTaskSchema>;
46
+
13
47
  export const clientMessageSchema = z.object({
14
48
  requestId: z.string().min(1),
15
49
  command: z.string().min(1),
@@ -20,6 +54,8 @@ export const clientMessageSchema = z.object({
20
54
  * d'autorisation, et chaque message se décrit lui-même, reconnexions comprises.
21
55
  */
22
56
  workspaceId: z.number().int().positive().optional(),
57
+ /** See {@link commandTaskSchema}. */
58
+ task: commandTaskSchema.optional(),
23
59
  payload: z.unknown()
24
60
  });
25
61
 
@@ -25,6 +25,7 @@ declare module 'deveye-sdk-client' {
25
25
  PointerEvent as ReactPointerEvent
26
26
  } from 'react';
27
27
  import type {
28
+ CommandTask,
28
29
  FeatureAccess,
29
30
  FeatureDomain,
30
31
  FeatureId,
@@ -137,22 +138,130 @@ declare module 'deveye-sdk-client' {
137
138
  className?: string;
138
139
  }
139
140
  export const ProgressBar: ComponentType<ProgressBarProps>;
140
- export interface ProgressDialogProps {
141
- open: boolean;
141
+
142
+ // ── Long operations ────────────────────────────────────────────────────
143
+ /** A running operation, as a screen reads it. */
144
+ export interface Task {
145
+ id: string;
146
+ feature: string;
147
+ itemId?: string;
148
+ key?: string;
142
149
  title: string;
143
- /** What is being done, and why it is worth the wait. */
144
- description?: string;
145
- /** See {@link ProgressBarProps.value}. */
150
+ subject?: string;
151
+ /** From 0 to 1 when the progress is measured. */
146
152
  value?: number;
147
- /** The current step, under the bar. */
148
153
  step?: string;
154
+ startedAt: number;
155
+ }
156
+ export interface TaskOptions<T = unknown> {
157
+ /** Your feature id (`manifest.id`): the icon, the name and the "Ouvrir" of its row. */
158
+ feature: string;
159
+ /** What is being done, as a noun phrase: "Suppression du point de restauration". */
160
+ title: string;
161
+ /** The fallback sentence of a failure, or the function that returns the whole note. */
162
+ failed: string | ((error: unknown) => ErrorNoteInput);
163
+ /** The item it targets: "Ouvrir" leads there, `useTasks` filters on it. */
164
+ itemId?: string | number;
165
+ /**
166
+ * The kind of operation. Two operations with the same feature,
167
+ * workspace, item and key never run together: the second one rejects
168
+ * with `TaskError` `conflict`, `run` is not called.
169
+ */
170
+ key?: string;
171
+ /** What it acts on (a name), to tell two rows with the same title apart. */
172
+ subject?: string;
173
+ /** Why it is worth the wait: shown in the dialog only. */
174
+ description?: string;
175
+ /** The success sentence of the operations panel; "Terminé." without it. */
176
+ done?: string | ((result: T) => string);
177
+ /** `false`: no dialog, the operation goes straight to the panel and your screen draws the progress. Default true. */
178
+ dialog?: boolean;
179
+ /** `false`: the dialog cannot be minimized, for a step whose follow-up needs the person (a question, a navigation). Default true. */
180
+ minimizable?: boolean;
181
+ /** The work runs in this tab, not on the server: closing the tab asks first. Default false. */
182
+ local?: boolean;
183
+ /** Offers "Annuler"; the operation leaves when `run` then rejects. */
184
+ cancel?: () => void;
185
+ /** Called once, the first time the dialog is minimized: close the sheet of an item that is going away. */
186
+ onDetach?: () => void;
187
+ }
188
+ export interface TaskContext {
189
+ /** The id of the operation, the one `useTasks` returns. */
190
+ id: string;
191
+ /**
192
+ * For THE command that does the work: the server follows it, its
193
+ * progress feeds the operation, and it runs in the workspace the
194
+ * operation started in.
195
+ */
196
+ sendOptions: SendOptions;
197
+ /** The progress of work done in the tab; `null` clears the value. */
198
+ report(update: { value?: number | null; step?: string | null }): void;
199
+ /** Brings the dialog back to the front, before a prompt that needs the person. */
200
+ raise(): void;
201
+ /** Where the operation started: `instanceId` is `null` for this instance. */
202
+ origin: { instanceId: number | null; workspaceId: number | null };
149
203
  }
150
204
  /**
151
- * A long operation under way: a dialog nothing closes while it lasts, and
152
- * a bar. Its owner closes it (`open: false`) when the operation ends or
153
- * gives up.
205
+ * Runs a long operation behind a dialog the person can minimize; it then
206
+ * lives in the operations area of the top bar, with its progress and its
207
+ * outcome. The promise resolves and rejects like `run`, so a screen that
208
+ * is still mounted keeps its own logic; one that is gone leaves the
209
+ * outcome to the panel.
210
+ *
211
+ * One command per operation: pass `task.sendOptions` to it. The server
212
+ * follows that command: a dropped socket or a reload does not lose it,
213
+ * and the account's other tabs show it in their own area. When the
214
+ * command could not leave, or when the server no longer knows the
215
+ * operation (it restarted), the promise rejects with a {@link TaskError}
216
+ * whose message already says what to do. A sequence of commands driven by
217
+ * the browser is a `local` operation that reports through `task.report`,
218
+ * and dies with its tab.
219
+ */
220
+ export function runTask<T>(
221
+ options: TaskOptions<T>,
222
+ run: (task: TaskContext) => Promise<T>
223
+ ): Promise<T>;
224
+ /**
225
+ * `runTask` for a wait your screen draws itself (a busy button, a bar in
226
+ * place): no dialog, and nothing in the operations area while the screen
227
+ * is there. If it unmounts before the end, the operation moves to the
228
+ * area, which then carries the outcome in its place. Options `dialog` and
229
+ * `minimizable` do not apply.
230
+ */
231
+ export function useTaskRunner(): <T>(
232
+ options: TaskOptions<T>,
233
+ run: (task: TaskContext) => Promise<T>
234
+ ) => Promise<T>;
235
+ /**
236
+ * The running operations of a feature in the active workspace, whichever
237
+ * screen started them, in this tab or in another one of the account:
238
+ * disable the conflicting actions, draw the progress in place, even after
239
+ * a remount or a reload.
240
+ */
241
+ export function useTasks(filter: {
242
+ feature: string;
243
+ itemId?: string | number;
244
+ key?: string;
245
+ }): readonly Task[];
246
+ /** The rejection an operation writes itself: `errorNote` keeps its message. */
247
+ export class TaskError extends Error {
248
+ constructor(
249
+ code: 'closed' | 'timeout' | 'lost' | 'conflict' | 'cancelled',
250
+ message: string
251
+ );
252
+ readonly code: 'closed' | 'timeout' | 'lost' | 'conflict' | 'cancelled';
253
+ }
254
+ export interface TaskProgressProps {
255
+ task: Task;
256
+ className?: string;
257
+ }
258
+ /**
259
+ * The progress of an operation drawn in the screen that started it: title,
260
+ * bar, step, and "Afficher" to bring its dialog back when this page holds
261
+ * it. The top bar sits under the veil of any open dialog, so a screen
262
+ * living in one shows this.
154
263
  */
155
- export const ProgressDialog: ComponentType<ProgressDialogProps>;
264
+ export const TaskProgress: ComponentType<TaskProgressProps>;
156
265
  export interface LogOutputProps {
157
266
  /** The raw log, ANSI sequences included: the component cleans it. */
158
267
  text: string;
@@ -259,6 +368,11 @@ declare module 'deveye-sdk-client' {
259
368
  searchable?: boolean | 'auto';
260
369
  /** Chips under the search, AND-combined, reset when the panel closes. */
261
370
  filters?: readonly SearchSelectFilter<T>[];
371
+ /**
372
+ * For a long list with long labels: the panel opens larger, grows by
373
+ * its corner, and the browser keeps the dragged size under this key.
374
+ */
375
+ resizeKey?: string;
262
376
  /** The trigger's id, for a label's `htmlFor`. */
263
377
  id?: string;
264
378
  /** The field the opening Dialog focuses first (`data-autofocus`). */
@@ -409,8 +523,14 @@ declare module 'deveye-sdk-client' {
409
523
  /** The height follows the content up to the viewport, then the body scrolls. */
410
524
  fill?: boolean;
411
525
  holdSecrecy?: boolean;
412
- /** Without the close button (a progress dialog). Default true. */
526
+ /** Without the close button: the dialog only leaves through its own actions. Default true. */
413
527
  closeButton?: boolean;
528
+ /**
529
+ * The box and its veil only appear after this delay, so shorter work
530
+ * never flickers. The layer is there from the opening: the screen
531
+ * underneath takes no click meanwhile.
532
+ */
533
+ appearDelayMs?: number;
414
534
  }>;
415
535
  /** The "Annuler" button of a Dialog footer: closes through the guarded close. */
416
536
  export const DialogCancelButton: ComponentType<
@@ -592,6 +712,21 @@ declare module 'deveye-sdk-client' {
592
712
  * cannot be projected) keeps its own wording.
593
713
  */
594
714
  export const ReadOnlyNotice: ComponentType<{ children: ReactNode }>;
715
+ /**
716
+ * The notice above a feature's list, or atop an item's sheet, when nothing
717
+ * would be sent: no channel declared for the feature, none checked for the
718
+ * item (or, for a feature that notifies in its own name, none checked for
719
+ * it). Its button opens the Notifications tab at that scale. Renders
720
+ * nothing while loading, for a reader who could not fix it, and when the
721
+ * scope has no Notifications tab. Its close button hides it for that
722
+ * reader on that page only (this list in this workspace, or this item's
723
+ * sheet), until they bring it back from their Profile.
724
+ */
725
+ export const NotificationsNotice: ComponentType<{
726
+ scope:
727
+ | { kind: 'feature'; feature: FeatureId }
728
+ | { kind: 'item'; feature: FeatureId; itemId: string; itemLabel: string };
729
+ }>;
595
730
  export interface ErrorNoteInput {
596
731
  message: string;
597
732
  /** The failure's code, `null` when it carries none: it decides whether a report is offered. */
@@ -819,7 +954,8 @@ declare module 'deveye-sdk-client' {
819
954
  /**
820
955
  * How long the command may stay silent, 15 s by default: stretch it for
821
956
  * a command that queries a slow third party. With `onProgress`, each
822
- * update restarts the count.
957
+ * update restarts the count. A command with `task` never times out
958
+ * once sent.
823
959
  */
824
960
  timeoutMs?: number;
825
961
  /** The updates the handler reports through `ctx.progress`, as they arrive. */
@@ -830,6 +966,12 @@ declare module 'deveye-sdk-client' {
830
966
  * across. The server checks membership and rights there as usual.
831
967
  */
832
968
  workspaceId?: number;
969
+ /**
970
+ * Marks the command as the one of a long operation, which the server
971
+ * then follows: it survives a reload or a dropped socket. Set by
972
+ * `runTask` in `task.sendOptions`; never build it yourself.
973
+ */
974
+ task?: CommandTask;
833
975
  }
834
976
  /**
835
977
  * The typed sender of any list of contracts (`featureApi` is it on a
package/src/sdk/client.ts CHANGED
@@ -519,6 +519,43 @@ export interface WhiteboardClientProvider {
519
519
  }>;
520
520
  }
521
521
 
522
+ /** An app of the workspace, as the Stores client provider lists it for a project's picker. */
523
+ export interface AppStoresLinkedCandidate {
524
+ id: number;
525
+ name: string;
526
+ /** Projected here from another workspace. */
527
+ foreign?: boolean;
528
+ }
529
+
530
+ /**
531
+ * What the Stores module offers the host's screens under
532
+ * `APPSTORES_CLIENT_PROVIDER`: the workspace's apps, a linked app shown inside
533
+ * a project's tab, and the feature's own app dialog.
534
+ */
535
+ export interface AppStoresClientProvider {
536
+ /** The workspace's apps, in the module's own order. */
537
+ listApps(): Promise<readonly AppStoresLinkedCandidate[]>;
538
+ /**
539
+ * The given apps, summarised for a project's dashboard tile, in ONE round
540
+ * trip. An id the caller cannot read, or that is gone, comes back
541
+ * `unavailable`, never as a throw. Never carries an amount of money: the
542
+ * module's revenue has a permission of its own.
543
+ */
544
+ summarize(appIds: readonly number[]): Promise<readonly SdkTileSummary[]>;
545
+ /**
546
+ * An app linked to a project: its stores, its downloads and ratings over
547
+ * the last days. Loads itself, follows the feature's invalidations, and
548
+ * renders the host's "unlink" as its trailing action.
549
+ */
550
+ LinkedApp: ComponentType<{ appId: number; canWrite: boolean; onUnlink: () => void }>;
551
+ /** The feature's app form, to follow a new app from a project. */
552
+ AppDialog: ComponentType<{
553
+ open: boolean;
554
+ onClose: () => void;
555
+ onSaved: (appId: number) => void;
556
+ }>;
557
+ }
558
+
522
559
  /**
523
560
  * What the Invoicing module offers other screens under
524
561
  * `INVOICING_CLIENT_PROVIDER`. It sends Invoicing's own command under the
@@ -258,7 +258,7 @@ export interface FeatureLink {
258
258
  }
259
259
 
260
260
  /** Hard cap on `links`: the "About" card stays a card. */
261
- export const MAX_FEATURE_LINKS = 7;
261
+ export const MAX_FEATURE_LINKS = 8;
262
262
 
263
263
  export interface FeatureManifest<Id extends FeatureId = FeatureId> {
264
264
  /** External modules: `x-<slug>`. Native features keep their enum id. */