@deveye/types 0.22.0 → 0.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,29 +1,38 @@
1
1
  # @deveye/types
2
2
 
3
- Les contrats partagés de [DevEye](https://github.com/Gerem66/DevEye) : types
4
- TypeScript et schémas zod, consommés par le serveur, le client et les modules
5
- de features.
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
- Le package sert ses sources directement (`src/*.ts`, aucun build) :
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`** — le domaine transverse (espaces, rôles, live, partage…),
10
- les protocoles (enveloppe WS, agent), le registre d'identité des features.
11
- - **`@deveye/types/sdk`** — le contrat des modules de features : `FeatureManifest`,
12
- `validateManifest`, ids `x-<slug>`.
13
- - **`@deveye/types/sdk/server`** — le contexte serveur d'un module (handlers,
14
- store, façade, service).
15
- - **`@deveye/types/sdk/client`** — les contrats de l'entrée client d'un module.
16
- - **`@deveye/types/sdk/testing`** — le harnais de test en mémoire des handlers.
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
- Le portrait typé du barrel `deveye-sdk-client` (le runtime que l'app fournit
19
- aux modules) est publié ici aussi (`src/sdk/client-ambient.d.ts`) ; la CI de
20
- DevEye vérifie mécaniquement que le vrai barrel l'honore.
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
- Pour écrire un module : partir du
23
- [template](https://github.com/Gerem66/DevEye-Feature-Template) et sa doc.
29
+ To write a module, start from the
30
+ [template](https://github.com/Gerem66/DevEye-Feature-Template) and its docs.
24
31
 
25
- ## Licence
32
+ ## License
26
33
 
27
- [MIT](LICENSE). Un module bâti sur ce paquet se licencie comme son auteur
28
- l'entend : le cœur de DevEye est sous AGPL-3.0, avec une exception pour ce qui
29
- ne passe que par ce SDK (`LICENSING.md` du dépôt de l'app).
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deveye/types",
3
- "version": "0.22.0",
3
+ "version": "0.23.0",
4
4
  "description": "Shared contracts (types + zod schemas) for DevEye apps",
5
5
  "main": "src/index.ts",
6
6
  "types": "src/index.ts",
@@ -60,10 +60,17 @@ export type HomeFeatureId = NativeHomeFeatureId | ExternalFeatureId;
60
60
  * - `secrecy` → password-encryption lock state + re-validation countdown.
61
61
  * - `live` → qui d'autre est dans l'espace, et où (bulles cliquables).
62
62
  * - `publicIp` → l'adresse publique par laquelle CE navigateur sort.
63
+ * - `search` → the magnifier that opens the feature search.
63
64
  * A module's widget is declared by its manifest (`topbarWidget`) and keyed by
64
65
  * its feature id (`homeTopbarWidgetIdSchema`).
65
66
  */
66
- export const nativeHomeTopbarWidgetIdSchema = z.enum(['weather', 'secrecy', 'live', 'publicIp']);
67
+ export const nativeHomeTopbarWidgetIdSchema = z.enum([
68
+ 'weather',
69
+ 'secrecy',
70
+ 'live',
71
+ 'publicIp',
72
+ 'search'
73
+ ]);
67
74
  export type NativeHomeTopbarWidgetId = z.infer<typeof nativeHomeTopbarWidgetIdSchema>;
68
75
 
69
76
  /**
@@ -122,12 +129,13 @@ export const shortcutItemSchema = z.object({
122
129
  export type ShortcutItem = z.infer<typeof shortcutItemSchema>;
123
130
 
124
131
  /**
125
- * Plafonds d'une section et d'un dossier. Exportés parce que le client doit
132
+ * Plafonds d'une section, d'un dossier et de la barre. Exportés parce que le client doit
126
133
  * refuser avant d'écrire : une disposition qui dépasse ne passe plus la
127
134
  * validation, et le client la relirait vide au démarrage suivant.
128
135
  */
129
136
  export const HOME_SECTION_MAX_TILES = 60;
130
137
  export const HOME_FOLDER_MAX_ITEMS = 20;
138
+ export const HOME_TOPBAR_MAX_WIDGETS = 10;
131
139
 
132
140
  /**
133
141
  * Un dossier de la grille : plusieurs fonctionnalités derrière une seule tuile,
@@ -234,7 +242,7 @@ export type HomeSection = z.infer<typeof homeSectionSchema>;
234
242
 
235
243
  export const homeLayoutSchema = z.object({
236
244
  /** Navbar mini-widgets — not a grid section, edited in the navbar itself. */
237
- topbar: z.array(homeTopbarWidgetIdSchema).max(10),
245
+ topbar: z.array(homeTopbarWidgetIdSchema).max(HOME_TOPBAR_MAX_WIDGETS),
238
246
  /** Ordered grid sections. Empty by default: a fresh home shows none. */
239
247
  sections: z.array(homeSectionSchema).max(12)
240
248
  });
package/src/index.ts CHANGED
@@ -519,6 +519,7 @@ export {
519
519
  nativeHomeTopbarWidgetIdSchema,
520
520
  HOME_FEATURE_IDS,
521
521
  HOME_FOLDER_MAX_ITEMS,
522
+ HOME_TOPBAR_MAX_WIDGETS,
522
523
  HOME_SECTION_MAX_TILES,
523
524
  isFeatureTile,
524
525
  isHomeFolder,
@@ -1270,7 +1270,12 @@ export const AGENT_SYNC_DELETE = 'sync.delete' as const;
1270
1270
  export const agentSyncDeletePayloadSchema = z.object({
1271
1271
  opId: syncOpId,
1272
1272
  shareId: z.number().int().positive(),
1273
- relPath: syncRelPath
1273
+ relPath: syncRelPath,
1274
+ /**
1275
+ * Asked for by the user: the file goes to the trash even if it changed since
1276
+ * the scan or was never indexed (unreadable, unportable name).
1277
+ */
1278
+ force: z.boolean().optional()
1274
1279
  });
1275
1280
  export type AgentSyncDeletePayload = z.infer<typeof agentSyncDeletePayloadSchema>;
1276
1281
 
@@ -52,6 +52,26 @@ declare module 'deveye-sdk-client' {
52
52
  export const TextInput: ComponentType<
53
53
  InputHTMLAttributes<HTMLInputElement> & { enableShowHideButton?: boolean; error?: string }
54
54
  >;
55
+ export interface ActionMenuItem {
56
+ label: string;
57
+ icon?: string;
58
+ onSelect: () => void;
59
+ /** A destructive action: shown in red. */
60
+ danger?: boolean;
61
+ disabled?: boolean;
62
+ /** What the action does, in one sentence, under the label. */
63
+ detail?: string;
64
+ }
65
+ export interface ActionMenuProps {
66
+ items: readonly ActionMenuItem[];
67
+ /** The button's name, for screen readers and the tooltip. */
68
+ label?: string;
69
+ className?: string;
70
+ /** The button's content in place of "⋯": the round look goes, `className` draws it. */
71
+ trigger?: ReactNode;
72
+ }
73
+ /** A "⋯" button that unfolds secondary actions above everything, never clipped by a scrolling parent. */
74
+ export const ActionMenu: ComponentType<ActionMenuProps>;
55
75
  export interface CopyButtonProps {
56
76
  value: string;
57
77
  /** What gets copied, for the tooltip and screen readers ("Copier la clé"). */
@@ -164,15 +184,8 @@ declare module 'deveye-sdk-client' {
164
184
  /** Chips sharing a key exclude each other: activating one releases the others. */
165
185
  exclusive?: string;
166
186
  }
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;
187
+ interface SearchSelectCommonProps<T extends string> {
174
188
  options: readonly SearchSelectOption<T>[];
175
- onChange: (value: T) => void;
176
189
  'aria-label': string;
177
190
  /** What the trigger shows when no option carries the current value. */
178
191
  placeholder?: string;
@@ -188,7 +201,28 @@ declare module 'deveye-sdk-client' {
188
201
  autoFocus?: boolean;
189
202
  disabled?: boolean;
190
203
  className?: string;
191
- }): ReactNode;
204
+ }
205
+ /**
206
+ * The app's dropdown. The search field (accent- and case-insensitive, group
207
+ * names included) only appears from eight choices on, or on request; filter
208
+ * chips can narrow the list. Safe inside a Dialog: the panel is portaled.
209
+ * With `multiple`, each option is a check box: picking one toggles it and
210
+ * keeps the panel open.
211
+ */
212
+ export function SearchSelect<T extends string>(
213
+ props: SearchSelectCommonProps<T> & {
214
+ multiple?: false;
215
+ value: T;
216
+ onChange: (value: T) => void;
217
+ }
218
+ ): ReactNode;
219
+ export function SearchSelect<T extends string>(
220
+ props: SearchSelectCommonProps<T> & {
221
+ multiple: true;
222
+ value: readonly T[];
223
+ onChange: (value: T[]) => void;
224
+ }
225
+ ): ReactNode;
192
226
  /**
193
227
  * A labelled range input. `valueLabel` is how the value reads ("24", "80 %");
194
228
  * `marks` sit under the track; `indicator` draws a discreet tick at a
package/src/sdk/client.ts CHANGED
@@ -95,7 +95,8 @@ export interface FeatureClient {
95
95
  * The compact topbar widget declared by `manifest.topbarWidget`. Rendered
96
96
  * with NO props: everything it shows must come through YOUR feature's
97
97
  * commands, which the server authorizes against the caller's grants. The
98
- * host mounts it only for members whose role grants your feature.
98
+ * host mounts it only for members whose role grants your feature, inside
99
+ * a button that opens your feature: put nothing interactive in it.
99
100
  */
100
101
  TopbarWidget?: ComponentType;
101
102
  /**
@@ -379,11 +380,14 @@ export interface GitClientProvider {
379
380
  * sync progress, and renders the host's "unlink" as its trailing action.
380
381
  */
381
382
  LinkedRepo: ComponentType<{ repoId: number; canWrite: boolean; onUnlink: () => void }>;
382
- /** The feature's repository form, to declare a new repository from a project. */
383
+ /**
384
+ * The feature's repository form, to declare new repositories from a
385
+ * project. Several can be checked at once: `onSaved` receives every id added.
386
+ */
383
387
  RepoDialog: ComponentType<{
384
388
  open: boolean;
385
389
  onClose: () => void;
386
- onSaved: (repoId: number) => void;
390
+ onSaved: (repoIds: readonly number[]) => void;
387
391
  }>;
388
392
  }
389
393
 
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 sixteen **native** feature ids, a closed enum (`WorkspaceFeatureId`);
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
  *
@@ -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?: { label: string; signupHint?: boolean };
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
@@ -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
@@ -42,6 +42,7 @@ import type {
42
42
 
43
43
  export {
44
44
  isPublicIp,
45
+ isRemoteFailure,
45
46
  isSafePublicUrl,
46
47
  NetRefused,
47
48
  resolvesPublicly,
@@ -88,7 +89,15 @@ export {
88
89
  * native features only through the declared {@link DevEyeFacade}.
89
90
  */
90
91
 
91
- /** Structural subset of the app logger (pino-compatible). */
92
+ /**
93
+ * Structural subset of the app logger (pino-compatible).
94
+ *
95
+ * `warn` and `error` are the operator's ladder: a bug, the instance's own
96
+ * configuration, a dependency of the instance. A failure a user's own side
97
+ * explains (their host unreachable, their credentials revoked, their agent
98
+ * outdated, a quota of theirs reached) goes out as `info` with the field
99
+ * `cause: 'user'`, see {@link logFailure}.
100
+ */
92
101
  export interface SdkLogger {
93
102
  debug(obj: unknown, msg?: string): void;
94
103
  info(obj: unknown, msg?: string): void;
@@ -96,6 +105,24 @@ export interface SdkLogger {
96
105
  error(obj: unknown, msg?: string): void;
97
106
  }
98
107
 
108
+ /**
109
+ * Logs a failure at the level its cause calls for. `userSide`: the user's own
110
+ * side explains it, and the line goes out as `info` tagged `cause: 'user'`, off
111
+ * the operator's ladder yet still searchable, so a wave of them across accounts
112
+ * still shows. Otherwise it stays at `level`. A failure nobody has explained is
113
+ * the instance's: pass `false`.
114
+ */
115
+ export function logFailure(
116
+ logger: SdkLogger,
117
+ userSide: boolean,
118
+ fields: Record<string, unknown>,
119
+ msg: string,
120
+ level: 'warn' | 'error' = 'warn'
121
+ ): void {
122
+ if (userSide) logger.info({ ...fields, cause: 'user' }, msg);
123
+ else logger[level](fields, msg);
124
+ }
125
+
99
126
  /**
100
127
  * The typed error a handler throws to reply with a clean protocol error.
101
128
  * Anything else becomes an opaque `internal` error. Codes you will use: