@deveye/types 0.25.1 → 0.25.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.25.1",
3
+ "version": "0.25.3",
4
4
  "description": "Shared contracts (types + zod schemas) for DevEye apps",
5
5
  "main": "src/index.ts",
6
6
  "types": "src/index.ts",
@@ -32,11 +32,15 @@ export const SYNC_RESUME_NONCES_MAX = Math.ceil((SYNC_RESUME_MAX_BLOCKS * 12) /
32
32
  export const SYNC_FINGERPRINT_SEP = '\u0001';
33
33
  /**
34
34
  * Mode de scan demandé à l'agent.
35
- * - `auto` → l'agent a le droit de répondre « rien n'a bougé » sans parcourir
36
- * le disque, en se contentant d'annoncer l'empreinte de ce qu'il détient ;
35
+ * - `delta` → l'agent a le droit de répondre « rien n'a bougé » sans parcourir
36
+ * le disque, en se contentant d'annoncer l'empreinte de ce qu'il détient,
37
+ * ou de ne parcourir que ce que son watcher a vu bouger et de n'envoyer que
38
+ * ces entrées (`delta: true` sur `sync.index`) ;
37
39
  * - `full` → parcours complet obligatoire (filet de sécurité horaire).
40
+ * Un agent qui ignore `delta` parcourt tout : la dissymétrie de version
41
+ * dégrade vers « on parcourt », jamais vers « on saute ».
38
42
  */
39
- export const syncScanModeSchema = z.enum(['auto', 'full']);
43
+ export const syncScanModeSchema = z.enum(['delta', 'full']);
40
44
  export type SyncScanMode = z.infer<typeof syncScanModeSchema>;
41
45
  /**
42
46
  * Empreinte d'un index : `{nombre}.{octets}.{sha256hex}`. Le pli est un XOR des
package/src/index.ts CHANGED
@@ -241,6 +241,7 @@ export {
241
241
  syncIndexEntrySchema,
242
242
  syncIndexLineSchema,
243
243
  syncIndexSkippedEntrySchema,
244
+ syncIndexGoneEntrySchema,
244
245
  syncShareAssignmentSchema
245
246
  } from './protocol/agent';
246
247
  export type {
@@ -328,6 +329,7 @@ export type {
328
329
  SyncIndexEntry,
329
330
  SyncIndexLine,
330
331
  SyncIndexSkippedEntry,
332
+ SyncIndexGoneEntry,
331
333
  SyncShareAssignment
332
334
  } from './protocol/agent';
333
335
 
@@ -438,10 +438,18 @@ export const syncIndexSkippedEntrySchema = z.object({
438
438
  });
439
439
  export type SyncIndexSkippedEntry = z.infer<typeof syncIndexSkippedEntrySchema>;
440
440
 
441
- /** One line of a `sync.index` batch: an indexed entry, or a skipped path. */
441
+ /** A path the agent no longer holds, in a `delta: true` reply only. */
442
+ export const syncIndexGoneEntrySchema = z.object({
443
+ relPath: syncRelPath,
444
+ kind: z.literal('gone')
445
+ });
446
+ export type SyncIndexGoneEntry = z.infer<typeof syncIndexGoneEntrySchema>;
447
+
448
+ /** One line of a `sync.index` batch: an indexed entry, a skipped path, or a path gone since the last scan. */
442
449
  export const syncIndexLineSchema = z.discriminatedUnion('kind', [
443
450
  syncIndexEntrySchema,
444
- syncIndexSkippedEntrySchema
451
+ syncIndexSkippedEntrySchema,
452
+ syncIndexGoneEntrySchema
445
453
  ]);
446
454
  export type SyncIndexLine = z.infer<typeof syncIndexLineSchema>;
447
455
 
@@ -454,14 +462,25 @@ export const agentSyncIndexPayloadSchema = z.object({
454
462
  entries: z.array(syncIndexLineSchema).max(SYNC_INDEX_BATCH_MAX),
455
463
  done: z.boolean(),
456
464
  /**
457
- * L'agent a-t-il réellement parcouru le disque ? `false` répond à un
458
- * `sync.scan` en mode `auto` sur un partage que le watcher sait intact :
459
- * aucune entrée, seule `fingerprint` est renseignée, et le serveur VÉRIFIE
460
- * qu'elle correspond à sa baseline (une vérification fausse coûte un scan
461
- * complet, jamais une divergence). Le défaut `true` rend un vieil agent
462
- * inoffensif.
465
+ * L'agent a-t-il parcouru le disque en entier ? `false` sans `delta`
466
+ * répond à un `sync.scan` en mode `delta` sur un partage que le watcher
467
+ * sait intact : aucune entrée, seule `fingerprint` est renseignée, et le
468
+ * serveur VÉRIFIE qu'elle correspond à sa baseline (une vérification
469
+ * fausse coûte un scan complet, jamais une divergence). `false` avec
470
+ * `delta` : seuls les dossiers touchés ont été relus, les chemins écartés
471
+ * ne sont pas tous là. Le défaut `true` rend un vieil agent inoffensif.
463
472
  */
464
473
  scanned: z.boolean().default(true),
474
+ /**
475
+ * Les entrées ne sont que ce qui a changé depuis le dernier scan (celles
476
+ * `gone` ont disparu) : l'index de l'appareil est la baseline du serveur
477
+ * corrigée de ces lignes, et `fingerprint` décrit cet index entier. Le
478
+ * serveur VÉRIFIE l'empreinte avant d'y croire, comme pour une réponse
479
+ * rapide. Jamais envoyé sans un `sync.scan` en mode `delta`, ou avec une
480
+ * empreinte `expected` que le parcours complet a retrouvée (`scanned`
481
+ * reste alors `true`).
482
+ */
483
+ delta: z.boolean().default(false),
465
484
  /** Empreinte de l'index détenu par l'agent, quand il sait la calculer. */
466
485
  fingerprint: syncIndexFingerprintSchema.nullable().default(null),
467
486
  /**
@@ -1095,7 +1114,13 @@ export const agentSyncScanPayloadSchema = z.object({
1095
1114
  * dissymétrie de version dégradent vers « scan complet », jamais vers
1096
1115
  * « saut ».
1097
1116
  */
1098
- mode: syncScanModeSchema.default('full')
1117
+ mode: syncScanModeSchema.default('full'),
1118
+ /**
1119
+ * L'empreinte de la baseline que le serveur tient pour cet appareil. Un
1120
+ * parcours complet qui la retrouve répond sans ses entrées (`delta: true`,
1121
+ * rien de changé) : le serveur n'a alors rien à recharger.
1122
+ */
1123
+ expected: syncIndexFingerprintSchema.optional()
1099
1124
  });
1100
1125
  export type AgentSyncScanPayload = z.infer<typeof agentSyncScanPayloadSchema>;
1101
1126
 
@@ -172,7 +172,7 @@ declare module 'deveye-sdk-client' {
172
172
  export const LogOutput: ComponentType<LogOutputProps>;
173
173
  export const Checkbox: ComponentType<{
174
174
  checked: boolean;
175
- /** Receives the state AFTER the click — no event to unwrap. */
175
+ /** Receives the state AFTER the click: no event to unwrap. */
176
176
  onChange: (checked: boolean) => void;
177
177
  children?: ReactNode;
178
178
  disabled?: boolean;
@@ -459,7 +459,7 @@ declare module 'deveye-sdk-client' {
459
459
  children: ReactNode;
460
460
  className?: string;
461
461
  }>;
462
- /** One confirmation dialog for the whole app — see ConfirmDialog. */
462
+ /** One confirmation dialog for the whole app (see ConfirmDialog). */
463
463
  export interface ConfirmRequest {
464
464
  title: string;
465
465
  description?: ReactNode;
@@ -772,7 +772,7 @@ declare module 'deveye-sdk-client' {
772
772
  /**
773
773
  * A resource key an EXTERNAL module may own: `x-<slug>.<name>`, as listed
774
774
  * in its manifest `resources`. The app's bus is typed on the closed union
775
- * of native keys plus this shape — an arbitrary string is refused there,
775
+ * of native keys plus this shape: an arbitrary string is refused there,
776
776
  * so it is refused here too.
777
777
  */
778
778
  export type ExternalResourceKey = `x-${string}.${string}`;
@@ -957,13 +957,20 @@ declare module 'deveye-sdk-client' {
957
957
  kind: PathExclusionKind;
958
958
  pattern: string;
959
959
  }
960
+ /** A name found in the walked folder, with what it weighs there, ready to show ("2,1 Go, 3 dossiers"). */
961
+ export interface PathExclusionFound {
962
+ name: string;
963
+ detail: string;
964
+ }
960
965
  /**
961
966
  * The exclusions of a walked folder (a CloudSync share, a backed-up
962
967
  * folder): exact path, component name or regex, relative to its root,
963
968
  * validated the way the agent will run them. `onAdd` gets a rule already
964
969
  * validated; `false` or a rejection keeps what was typed (say why where
965
970
  * you show your errors). `scope` ends the suggestions' tooltip ("le
966
- * partage", "le dossier").
971
+ * partage", "le dossier"). `found` lists names found in the folder, first
972
+ * among the suggestions with their weight; `onAddFound` takes their click
973
+ * (by default `onAdd`, as a name rule).
967
974
  */
968
975
  export const PathExclusionsEditor: ComponentType<{
969
976
  items: readonly PathExclusionItem[];
@@ -972,6 +979,8 @@ declare module 'deveye-sdk-client' {
972
979
  canWrite: boolean;
973
980
  scope: string;
974
981
  disabled?: boolean;
982
+ found?: readonly PathExclusionFound[];
983
+ onAddFound?: (name: string) => boolean | Promise<boolean>;
975
984
  }>;
976
985
  /**
977
986
  * The workspace's enrolled devices, live: what the Devices module offers
package/src/sdk/client.ts CHANGED
@@ -95,6 +95,13 @@ export interface FeatureClient {
95
95
  * (`'notifications'`, `'permissions'`) need no panel.
96
96
  */
97
97
  settingsPanels?: Readonly<Record<string, ComponentType<SettingsPanelProps>>>;
98
+ /**
99
+ * Whether a custom tab applies to this scope, for a tab that only means
100
+ * something to some items (Mail's Access tab, for a mailbox the Mail
101
+ * server hosts). Asked when the settings open, the tab hidden until the
102
+ * answer. Omitted, every declared tab shows.
103
+ */
104
+ settingsTabApplies?(tabId: string, scope: SdkSettingsScope): Promise<boolean>;
98
105
  /**
99
106
  * The compact topbar widget declared by `manifest.topbarWidget`. Rendered
100
107
  * with NO props: everything it shows must come through YOUR feature's
@@ -521,3 +528,15 @@ export interface MailClientProvider {
521
528
  prefill?: MailAccountPrefill;
522
529
  }>;
523
530
  }
531
+
532
+ /**
533
+ * What the Mail server module offers under `MAILSERVER_CLIENT_PROVIDER`: Mail
534
+ * shows, on an account whose address the server hosts, the mailbox's own
535
+ * Access tab (its application passwords) and the way to its sheet.
536
+ */
537
+ export interface MailserverClientProvider {
538
+ /** The hosted mailbox holding this address among those the caller can read, or null. */
539
+ findByAddress(address: string): Promise<{ id: number } | null>;
540
+ /** The mailbox's Access settings panel, to mount under a scope naming that mailbox. */
541
+ AccessPanel: ComponentType<SettingsPanelProps>;
542
+ }
@@ -203,7 +203,14 @@ test('validateManifest checks quotas and the account entry', () => {
203
203
  { quotas: [{ key: 'monitors', label: 'm', stock: true, perOperation: true }] },
204
204
  'a per-operation limit is no stock'
205
205
  );
206
- rejects({ accountOnly: true }, 'accountOnly requires accountEntry');
206
+ rejects({ accountOnly: true }, 'accountOnly requires accountEntry or adminTabs');
207
+ assert.doesNotThrow(() =>
208
+ validateManifest({
209
+ ...base,
210
+ accountOnly: true,
211
+ adminTabs: [{ id: 'rules', label: 'Rules', moderation: true }]
212
+ })
213
+ );
207
214
  rejects({ accountOnly: true, accountEntry: { label: 'S' }, tile: {} }, 'no tile');
208
215
  rejects({ accountEntry: { label: ' ' } }, 'requires a label');
209
216
  });
@@ -384,9 +384,11 @@ export interface FeatureManifest<Id extends FeatureId = FeatureId> {
384
384
  */
385
385
  adminTabs?: readonly AdminTabSpec[];
386
386
  /**
387
- * The module lives in the user menu only: no card, no row in the roles
388
- * screen, `Widget` and `Full` not required. Requires `accountEntry`, no
389
- * items, and every command scoped to the account (`access.scope`).
387
+ * The module has no card and no row in the roles screen, and `Widget` and
388
+ * `Full` are not required: it lives in the user menu (`accountEntry`), or
389
+ * in the feature administration popup only (`adminTabs`, a module that
390
+ * serves the instance rather than its members). Requires one of the two,
391
+ * no items, and every command scoped to the account (`access.scope`).
390
392
  */
391
393
  accountOnly?: boolean;
392
394
 
@@ -551,7 +553,9 @@ export function validateManifest(m: FeatureManifest): void {
551
553
  if (!tab.label.trim()) fail(m.id, `admin tab « ${tab.id} »: empty label`);
552
554
  }
553
555
  if (m.accountOnly) {
554
- if (!m.accountEntry) fail(m.id, 'accountOnly requires accountEntry');
556
+ if (!m.accountEntry && (m.adminTabs ?? []).length === 0) {
557
+ fail(m.id, 'accountOnly requires accountEntry or adminTabs');
558
+ }
555
559
  if (m.hasItems) fail(m.id, 'accountOnly modules own no items');
556
560
  if (m.tile || m.topbarWidget || m.settings) {
557
561
  fail(m.id, 'accountOnly modules have no tile, topbar widget or settings');
package/src/sdk/net.ts CHANGED
@@ -159,6 +159,8 @@ export interface SafeFetchOptions {
159
159
  contentType?: string;
160
160
  accept?: string;
161
161
  userAgent?: string;
162
+ /** Extra request headers (an API key the service expects); `accept` and `user-agent` above win. */
163
+ headers?: Readonly<Record<string, string>>;
162
164
  }
163
165
 
164
166
  /**
@@ -183,6 +185,7 @@ export async function safeFetchText(raw: string, options: SafeFetchOptions): Pro
183
185
  redirect: 'manual',
184
186
  signal: AbortSignal.timeout(options.timeoutMs),
185
187
  headers: {
188
+ ...options.headers,
186
189
  accept: options.accept ?? 'text/plain, */*',
187
190
  'user-agent': options.userAgent ?? 'DevEye/1.0'
188
191
  }
@@ -288,6 +288,13 @@ export interface MailTransportMessage {
288
288
  */
289
289
  export const MAIL_CLIENT_PROVIDER = 'mail.client' as const;
290
290
 
291
+ /**
292
+ * Key under `FeatureClient.providers` for what the Mail server offers Mail's
293
+ * screens: whether an address is hosted there, and the Access tab of its
294
+ * mailbox. The contract type lives in `@deveye/types/sdk/client`.
295
+ */
296
+ export const MAILSERVER_CLIENT_PROVIDER = 'mailserver.client' as const;
297
+
291
298
  /**
292
299
  * Key under `FeatureService.providers` for the Audience sites the app's
293
300
  * Projects feature links to: same shape and same reason as
@@ -936,3 +943,79 @@ export interface AccountPlanProvider {
936
943
  /** `fresh`: never from a cache, the host is about to pause or resume on the answer. */
937
944
  planFor(userId: number, opts?: { fresh?: boolean }): Promise<AccountPlan>;
938
945
  }
946
+
947
+ /**
948
+ * Key under `FeatureService.providers` of the automatic moderation: the
949
+ * instance's lists of banned content (file fingerprints and name patterns),
950
+ * kept by the moderation module and consulted by every feature that stores or
951
+ * publishes files (Hosting, CloudSync). Absent (module not installed), nothing
952
+ * is checked and the features behave as before: the caller degrades to
953
+ * "no hit".
954
+ */
955
+ export const MODERATION_PROVIDER = 'moderation.check' as const;
956
+
957
+ /** Why a content is banned, in the vocabulary of the public report forms. */
958
+ export const MODERATION_REASONS = [
959
+ 'illegal',
960
+ 'copyright',
961
+ 'malware',
962
+ 'privacy',
963
+ 'minors',
964
+ 'other'
965
+ ] as const;
966
+ export type ModerationReason = (typeof MODERATION_REASONS)[number];
967
+
968
+ /**
969
+ * Where the content goes: `public` when anyone with an address can download it
970
+ * (a Hosting folder), `private` when it stays with its owner and their devices
971
+ * (a CloudSync share). A rule says which exposures it covers.
972
+ */
973
+ export type ModerationExposure = 'public' | 'private';
974
+
975
+ export interface ModerationSubject {
976
+ /** The lowercase hex SHA-256 of the plaintext; `null` when the host cannot compute it (end-to-end encrypted content). */
977
+ sha256: string | null;
978
+ /** The file name as the user named it, without its folders. */
979
+ name: string;
980
+ exposure: ModerationExposure;
981
+ /** For the moderators' journal: who sent what, and where. */
982
+ origin: {
983
+ /** The feature's id (`x-hosting`, `cloudsync`). */
984
+ feature: string;
985
+ workspaceId: number | null;
986
+ /** `null` for a transfer a device drives without a session. */
987
+ userId: number | null;
988
+ /** The item the file belongs to (a folder's name, a share's name), as the moderators read it. */
989
+ context: string;
990
+ };
991
+ size?: number;
992
+ }
993
+
994
+ export interface ModerationHit {
995
+ ruleId: number;
996
+ kind: 'fingerprint' | 'name';
997
+ reason: ModerationReason;
998
+ /** What the user is told, one sentence: "Logiciel malveillant connu". */
999
+ label: string;
1000
+ }
1001
+
1002
+ export interface ModerationProvider {
1003
+ /**
1004
+ * `null` when nothing matches. A hit is recorded for the moderators
1005
+ * (feature, context, name, account) before it is returned; the caller
1006
+ * decides what becomes of the content: hold it, refuse it.
1007
+ */
1008
+ check(subject: ModerationSubject): Promise<ModerationHit | null>;
1009
+ /**
1010
+ * Bans these fingerprints from now on (after a takedown): the ones already
1011
+ * banned are left as they are. Returns how many were added. Nothing already
1012
+ * stored is re-examined.
1013
+ */
1014
+ ban(input: {
1015
+ fingerprints: readonly string[];
1016
+ reason: ModerationReason;
1017
+ label: string;
1018
+ /** The moderator's account, `null` for the instance. */
1019
+ by: number | null;
1020
+ }): Promise<number>;
1021
+ }