@deveye/types 0.24.2 → 0.24.3

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.24.2",
3
+ "version": "0.24.3",
4
4
  "description": "Shared contracts (types + zod schemas) for DevEye apps",
5
5
  "main": "src/index.ts",
6
6
  "types": "src/index.ts",
@@ -51,10 +51,11 @@ export interface FeatureDescriptor {
51
51
  * (un jeton, une destination) que chaque élément ne fait que désigner.
52
52
  * Ouvre l'onglet « Sources » à l'échelle de la fonctionnalité, seul endroit
53
53
  * où elles se créent et se corrigent ; `hint` est la phrase de tête de
54
- * l'onglet. Les canaux de notification suivent la même logique dans
55
- * l'onglet « Notifications » (voir `notifies`).
54
+ * l'onglet, `label` et `icon` son nom et son icône quand « Sources » dirait
55
+ * mal ce qu'il range (des destinations). Les canaux de notification suivent
56
+ * la même logique dans l'onglet « Notifications » (voir `notifies`).
56
57
  */
57
- sources?: { hint: string };
58
+ sources?: { hint: string; label?: string; icon?: string };
58
59
  /**
59
60
  * La phrase de tête de l'onglet Notifications : QUAND la fonctionnalité
60
61
  * prévient. Sans elle, l'onglet liste des canaux sans dire à quoi ils
@@ -245,7 +246,9 @@ export const FEATURE_REGISTRY: readonly (FeatureDescriptor & { id: WorkspaceFeat
245
246
  hasItems: true,
246
247
  itemNoun: 'travail',
247
248
  sources: {
248
- hint: 'Les destinations d’archives de l’espace : un dossier du serveur, une machine, un bucket S3, un serveur SFTP ou WebDAV. Chaque travail écrit vers l’une d’elles ; la corriger corrige d’un coup tous les travaux qui s’en servent.'
249
+ hint: 'Les destinations d’archives de l’espace : un dossier du serveur, une machine, un bucket S3, un serveur SFTP ou WebDAV. Chaque travail écrit vers l’une d’elles ; la corriger corrige d’un coup tous les travaux qui s’en servent.',
250
+ label: 'Destinations',
251
+ icon: 'cloud'
249
252
  },
250
253
  shareTier: 'open'
251
254
  },
@@ -97,12 +97,15 @@ export type UserSecurity = z.infer<typeof userSecuritySchema>;
97
97
  * se retire jamais : la bulle se montre une fois dans la vie d'un compte.
98
98
  * - `homeLayoutHintDismissed`, `aboutHintDismissed` : de même pour les bulles
99
99
  * du bouton d'organisation de l'accueil et du numéro de version.
100
+ * - `hideHomeAddTile` : ne pas afficher, hors organisation, la carte d'ajout au
101
+ * bout de chaque section de l'accueil.
100
102
  */
101
103
  export const userSettingFlagSchema = z.enum([
102
104
  'hideLiveCursors',
103
105
  'feedbackHintDismissed',
104
106
  'homeLayoutHintDismissed',
105
- 'aboutHintDismissed'
107
+ 'aboutHintDismissed',
108
+ 'hideHomeAddTile'
106
109
  ]);
107
110
  export type UserSettingFlag = z.infer<typeof userSettingFlagSchema>;
108
111
 
@@ -49,6 +49,13 @@ declare module 'deveye-sdk-client' {
49
49
  ButtonHTMLAttributes<HTMLButtonElement> & {
50
50
  variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
51
51
  icon?: string;
52
+ /**
53
+ * Renders a real link with the button's look, so the browser opens,
54
+ * copies or tabs it itself. `target='_blank'` gets its safe `rel`.
55
+ */
56
+ href?: string;
57
+ target?: string;
58
+ rel?: string;
52
59
  }
53
60
  >;
54
61
  export const TextInput: ComponentType<
@@ -233,6 +240,14 @@ declare module 'deveye-sdk-client' {
233
240
  placeholder?: string;
234
241
  searchPlaceholder?: string;
235
242
  emptyText?: string;
243
+ /**
244
+ * Groups always listed, in this order, even without options: one
245
+ * without any reads `emptyGroupText` ("Aucun") under its heading.
246
+ * Groups missing here follow in order of first appearance. While a
247
+ * search or a chip narrows the list, empty groups step aside.
248
+ */
249
+ groups?: readonly string[];
250
+ emptyGroupText?: string;
236
251
  /** The search field: `'auto'` (default) shows it from eight choices on. */
237
252
  searchable?: boolean | 'auto';
238
253
  /** Chips under the search, AND-combined, reset when the panel closes. */
@@ -1014,8 +1029,20 @@ declare module 'deveye-sdk-client' {
1014
1029
  onChange: (next: { theme: T; accent: string }) => void;
1015
1030
  preview?: ReactNode;
1016
1031
  }): ReactNode;
1017
- /** Opens an account view (`manifest.accountEntry`): the given module's, or the first one. No-op without any. */
1018
- export function openAccountView(featureId?: string): void;
1032
+ /**
1033
+ * Opens an account view (`manifest.accountEntry`): the given module's, or
1034
+ * the first one. No-op without any. `hint` reaches the view once, on its
1035
+ * mount (`'pro'` preselects the paid offer of the subscription view).
1036
+ */
1037
+ export function openAccountView(featureId?: string, hint?: string): void;
1038
+ /**
1039
+ * The app's "available with the Pro offer" prompt, before anything is
1040
+ * sent: for a screen that already knows its owner's plan leaves a feature
1041
+ * out (a quota whose limit is 0). The workspace owner is offered the plans,
1042
+ * a member is told whom to ask. A command refused with a limit of 0 opens
1043
+ * the same prompt by itself.
1044
+ */
1045
+ export function openProOffer(input: { title?: string; body: ReactNode }): void;
1019
1046
  export interface LiveOutlineProps {
1020
1047
  'data-live-peer'?: true;
1021
1048
  style?: CSSProperties;
package/src/sdk/client.ts CHANGED
@@ -51,7 +51,7 @@ export interface AccountViewProps {
51
51
  close(): void;
52
52
  /** The viewer is a global administrator of this DevEye. */
53
53
  isAdmin: boolean;
54
- /** The hint a sign-up carried (`manifest.accountEntry.signupHint`), delivered once. */
54
+ /** The hint a sign-up carried (`manifest.accountEntry.signupHint`) or `openAccountView` passed, delivered once. */
55
55
  hint?: string;
56
56
  }
57
57
 
@@ -272,8 +272,12 @@ export interface FeatureManifest<Id extends FeatureId = FeatureId> {
272
272
  * Masculine by default.
273
273
  */
274
274
  itemNounGender?: 'm' | 'f';
275
- /** Feature-scope reusable settings (API keys, destinations). Opens the Sources tab. */
276
- sources?: { hint: string };
275
+ /**
276
+ * Feature-scope reusable settings (API keys, destinations). Opens the
277
+ * Sources tab, under `label` and `icon` when "Sources" would misname what
278
+ * it holds.
279
+ */
280
+ sources?: { hint: string; label?: string; icon?: string };
277
281
  /**
278
282
  * WHEN the feature notifies, as the lead sentence of its Notifications tab.
279
283
  * Required with `notifies`: a tab that lists channels without saying what
@@ -11,42 +11,116 @@
11
11
  * itself.
12
12
  */
13
13
 
14
- /** Key under `FeatureService.providers` for the CloudSync backup source. */
14
+ import type { SdkAccessVerdict } from './server';
15
+
16
+ /**
17
+ * Keys under `FeatureService.providers` of the file trees the Backup feature
18
+ * archives as a plain `tar`: a CloudSync share, a Hosting folder. Both offer a
19
+ * `TreeBackupProvider`. Absent (module not installed), the source kind leaves
20
+ * the picker and a job that names it fails its run with a clean message.
21
+ */
15
22
  export const CLOUDSYNC_BACKUP_PROVIDER = 'cloudsync.backup' as const;
23
+ export const HOSTING_BACKUP_PROVIDER = 'hosting.backup' as const;
16
24
 
17
- export interface SyncBackupShare {
25
+ /** One backupable tree of a workspace. */
26
+ export interface TreeBackupRoot {
18
27
  id: number;
19
28
  name: string;
20
29
  workspaceId: number;
21
- userId: number;
22
- }
23
-
24
- export interface SyncBackupStats {
25
30
  fileCount: number;
26
- liveBytes: number;
31
+ bytes: number;
27
32
  }
28
33
 
29
- export interface SyncBackupFile {
34
+ export interface TreeBackupEntry {
35
+ /** Relative to the root, `/`-separated. */
30
36
  relPath: string;
31
37
  kind: 'file' | 'dir';
32
- hash: string;
38
+ /** The exact plaintext size: the tar header is written from it before the bytes. */
33
39
  size: number;
40
+ /** Unix milliseconds. */
34
41
  mtime: number;
35
42
  mode: number | null;
43
+ /** What `open` takes back for a file (a content hash, an entry id). */
44
+ ref: string;
45
+ }
46
+
47
+ export interface TreeBackupProvider {
48
+ /** The workspace's own trees (a projection is not a source), those the server can read. */
49
+ list(workspaceId: number): Promise<readonly TreeBackupRoot[]>;
50
+ /** `null` when unknown, unreadable, or not this workspace's own. */
51
+ find(id: number, workspaceId: number): Promise<TreeBackupRoot | null>;
52
+ entries(id: number): Promise<readonly TreeBackupEntry[]>;
53
+ /** Decrypted plaintext stream of one file. */
54
+ open(id: number, ref: string): Promise<AsyncIterable<Uint8Array>>;
55
+ /**
56
+ * May this member, without a session, read the tree's files? The same
57
+ * right as downloading one from the feature's screens, the item's
58
+ * override included.
59
+ */
60
+ authorize(id: number, workspaceId: number, userId: number): Promise<SdkAccessVerdict>;
36
61
  }
37
62
 
38
63
  /**
39
- * What the Backup feature needs from CloudSync, inverted: the CloudSync module
40
- * registers this; Backup consumes it. Absent provider = the backup run fails
41
- * with a clean "module not installed" error and the UI hides the source kind.
64
+ * Key of the Mail server's mailboxes as a backup source: the messages, their
65
+ * folders and flags, decrypted, for an archive a stock IMAP server reads.
42
66
  */
43
- export interface CloudSyncBackupProvider {
44
- findShare(shareId: number): Promise<SyncBackupShare | null>;
45
- listShares(workspaceId: number): Promise<readonly SyncBackupShare[]>;
46
- statsByShare(shareId: number): Promise<SyncBackupStats>;
47
- listPresentFiles(shareId: number): Promise<readonly SyncBackupFile[]>;
48
- /** Decrypted plaintext stream of one blob. */
49
- openBlob(shareId: number, hash: string): Promise<AsyncIterable<Uint8Array>>;
67
+ export const MAILSERVER_BACKUP_PROVIDER = 'mailserver.backup' as const;
68
+
69
+ export interface MailBackupMailbox {
70
+ id: number;
71
+ address: string;
72
+ workspaceId: number;
73
+ messageCount: number;
74
+ bytes: number;
75
+ }
76
+
77
+ export interface MailBackupFolder {
78
+ id: number;
79
+ /** `/`-separated, UTF-8; `INBOX` is the inbox. */
80
+ path: string;
81
+ /** `\Sent`, `\Drafts`, `\Trash`, `\Junk`, `\Archive`, or `null`. */
82
+ specialUse: string | null;
83
+ subscribed: boolean;
84
+ /** The IMAP keywords its messages carry, each once. */
85
+ keywords: readonly string[];
86
+ }
87
+
88
+ export type MailBackupFlag = 'seen' | 'answered' | 'flagged' | 'deleted' | 'draft';
89
+
90
+ export interface MailBackupMessage {
91
+ id: number;
92
+ uid: number;
93
+ /** The exact plaintext size of the RFC 822 message. */
94
+ size: number;
95
+ /** Unix seconds. */
96
+ internalDate: number;
97
+ flags: readonly MailBackupFlag[];
98
+ keywords: readonly string[];
99
+ }
100
+
101
+ export interface MailServerBackupProvider {
102
+ /** The workspace's own addresses (a projection is not a source). */
103
+ listMailboxes(workspaceId: number): Promise<readonly MailBackupMailbox[]>;
104
+ findMailbox(mailboxId: number, workspaceId: number): Promise<MailBackupMailbox | null>;
105
+ /** Every folder, empty ones included: a restore must find them. */
106
+ folders(mailboxId: number): Promise<readonly MailBackupFolder[]>;
107
+ /** A page of a folder's messages, by ascending uid after `afterUid`. */
108
+ messages(
109
+ mailboxId: number,
110
+ folderId: number,
111
+ afterUid: number,
112
+ limit: number
113
+ ): Promise<readonly MailBackupMessage[]>;
114
+ /**
115
+ * Opens one message BEFORE resolving, so a message expunged since the
116
+ * listing answers `null` here rather than failing mid-stream.
117
+ */
118
+ open(mailboxId: number, messageId: number): Promise<AsyncIterable<Uint8Array> | null>;
119
+ /**
120
+ * May this member, without a session, read the mail of this address? Who
121
+ * can reset its password can; mere write access to the Mail server cannot.
122
+ */
123
+ authorize(mailboxId: number, workspaceId: number, userId: number): Promise<SdkAccessVerdict>;
50
124
  }
51
125
 
52
126
  /**
@@ -87,6 +161,12 @@ export interface DatabaseBackupProvider {
87
161
  findDatabase(databaseId: number, workspaceId: number): Promise<DatabaseBackupCandidate | null>;
88
162
  /** null when the database is unknown to this workspace. */
89
163
  openAccess(databaseId: number, workspaceId: number): Promise<DatabaseBackupAccess | null>;
164
+ /**
165
+ * May this member, without a session, read the database's data? The same
166
+ * right as exploring it from the feature's screens, the item's override
167
+ * included: a dump holds every row.
168
+ */
169
+ authorize(databaseId: number, workspaceId: number, userId: number): Promise<SdkAccessVerdict>;
90
170
  }
91
171
 
92
172
  /**
@@ -313,12 +393,41 @@ export interface AudienceSelfProvider {
313
393
  export const AUDIENCE_CLIENT_PROVIDER = 'audience.client' as const;
314
394
 
315
395
  /**
316
- * Key under `FeatureService.providers` for the Git repositories the app's
317
- * Projects feature links to: same shape and same reason as
318
- * `UPTIME_ITEMS_PROVIDER` (`project_repo_links` is Projects' table).
396
+ * Key under `FeatureService.providers` for the Git repositories other
397
+ * features build on: Projects links to them (`project_repo_links` is
398
+ * Projects' table, same reason as `UPTIME_ITEMS_PROVIDER`), and a code
399
+ * scanner follows them and clones them.
319
400
  */
320
401
  export const GIT_ITEMS_PROVIDER = 'git.items' as const;
321
402
 
403
+ /** A repository at home in one of the workspaces asked for, as `listHome` lists it. */
404
+ export interface GitHomeRepo {
405
+ id: number;
406
+ workspaceId: number;
407
+ /** The head of the default branch as the last sync saw it, `null` before any sync. */
408
+ headSha: string | null;
409
+ /** When that head was read at the forge (epoch seconds): a consumer that cloned later knows better. */
410
+ headSeenAt: number | null;
411
+ }
412
+
413
+ /** A repository as read from its home: its name, where it lives, its default branch. */
414
+ export interface GitRepoDescription {
415
+ workspaceId: number;
416
+ /** `owner/repo`. */
417
+ label: string;
418
+ /** The https URL a clone fetches from. */
419
+ cloneUrl: string;
420
+ /** The repository's page at the forge. */
421
+ webUrl: string;
422
+ /** `null` until a sync told it; a clone then follows the forge's HEAD. */
423
+ defaultBranch: string | null;
424
+ }
425
+
426
+ export interface GitCheckout extends GitRepoDescription {
427
+ /** The token of the repository's credential, `null` for a public repository or a token the server cannot read. */
428
+ token: string | null;
429
+ }
430
+
322
431
  export interface GitItemsProvider {
323
432
  /** Is this repository visible from this workspace: its home, or one it is projected into? */
324
433
  exists(repoId: number, workspaceId: number): Promise<boolean>;
@@ -330,6 +439,73 @@ export interface GitItemsProvider {
330
439
  * an id.
331
440
  */
332
441
  labelOf(repoId: number, workspaceId: number): Promise<string | null>;
442
+ /**
443
+ * Every repository whose HOME is one of `workspaceIds`, oldest first, with
444
+ * nothing decrypted: what a feature that follows the workspace's
445
+ * repositories reconciles its own rows against. A projection is not
446
+ * listed, its home workspace holds it.
447
+ */
448
+ listHome(workspaceIds: readonly number[]): Promise<readonly GitHomeRepo[]>;
449
+ /** The repository read from its home workspace, `null` when gone or unreadable. */
450
+ describe(repoId: number, workspaceId: number): Promise<GitRepoDescription | null>;
451
+ /**
452
+ * `describe` plus the token a clone presents to the forge. Hands a secret
453
+ * out, like `DatabaseBackupProvider.openAccess`: call it from a sessionless
454
+ * service, right before the clone, and never store what it returns.
455
+ */
456
+ openCheckout(repoId: number, workspaceId: number): Promise<GitCheckout | null>;
457
+ }
458
+
459
+ /**
460
+ * Key under `FeatureService.providers` for the CVE catalogue: the CVEs that
461
+ * affect a given product at a given version, read from the catalogue the CVE
462
+ * feature keeps for the whole server. A lookup never calls the NVD itself:
463
+ * the catalogue is the shared cache, filled by one ingestion queue that keeps
464
+ * to the NVD's quota.
465
+ */
466
+ export const CVE_LOOKUP_PROVIDER = 'cve.lookup' as const;
467
+
468
+ /** A product as the NVD's CPE names it: `f5` / `nginx`, `nodejs` / `node.js`. */
469
+ export interface CveProductRef {
470
+ vendor: string;
471
+ product: string;
472
+ }
473
+
474
+ export interface CveLookupItem extends CveProductRef {
475
+ /** An exact version (`1.25.3`). A floating one (`1.25`) compares to nothing. */
476
+ version: string;
477
+ }
478
+
479
+ export interface CveLookupHit {
480
+ cveId: string;
481
+ severity: 'none' | 'low' | 'medium' | 'high' | 'critical';
482
+ score: number | null;
483
+ summary: string;
484
+ /** Epoch seconds. */
485
+ published: number;
486
+ /** The first version out of the affected range, when the NVD gives one. */
487
+ fixedIn: string | null;
488
+ }
489
+
490
+ export interface CveLookupResult {
491
+ /**
492
+ * `stale`: the catalogue cannot vouch for these products yet (their past
493
+ * CVEs are still being fetched, or the NVD has not answered for a day):
494
+ * `hits` is what is known, `reason` says why it may be incomplete.
495
+ */
496
+ status: 'ok' | 'stale';
497
+ reason: string | null;
498
+ hits: readonly { item: CveLookupItem; cves: readonly CveLookupHit[] }[];
499
+ }
500
+
501
+ export interface CveLookupProvider {
502
+ /**
503
+ * Products to keep in the catalogue for good: their whole CVE history is
504
+ * fetched once, then follows the ordinary feed, and the catalogue's
505
+ * retention spares them. Idempotent; cheap to call on every analysis.
506
+ */
507
+ watch(products: readonly CveProductRef[]): Promise<void>;
508
+ affecting(items: readonly CveLookupItem[]): Promise<CveLookupResult>;
333
509
  }
334
510
 
335
511
  /**