@deveye/types 0.25.0 → 0.25.2

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.0",
3
+ "version": "0.25.2",
4
4
  "description": "Shared contracts (types + zod schemas) for DevEye apps",
5
5
  "main": "src/index.ts",
6
6
  "types": "src/index.ts",
@@ -139,7 +139,13 @@ export const feedbackEntrySchema = z.object({
139
139
  snapshot: feedbackSnapshotSchema.nullable(),
140
140
  handledAt: z.number().int().nonnegative().nullable(),
141
141
  handledBy: z.number().int().positive().nullable(),
142
- handledByName: z.string().nullable()
142
+ handledByName: z.string().nullable(),
143
+ /**
144
+ * When the report lost its author, message, address and the browser
145
+ * details that describe a person, keeping its technical part; null while
146
+ * intact.
147
+ */
148
+ anonymizedAt: z.number().int().nonnegative().nullable()
143
149
  });
144
150
  export type FeedbackEntry = z.infer<typeof feedbackEntrySchema>;
145
151
 
@@ -157,4 +163,5 @@ export interface FeedbackRow {
157
163
  created: number;
158
164
  handled_at: number | null;
159
165
  handled_by: number | null;
166
+ anonymized_at: number | null;
160
167
  }
@@ -1,8 +1,18 @@
1
1
  import { z } from 'zod';
2
+ import { loginStepSchema } from '../http/auth';
2
3
 
3
4
  /** How long a trusted browser stays trusted without a login, in days. */
4
5
  export const TRUSTED_BROWSER_DAYS = 90;
5
6
 
7
+ /** How long a successful login stays in the account's history, in days. */
8
+ export const LOGIN_HISTORY_DAYS = 90;
9
+
10
+ /** The part of that history the account is shown by default, in days. */
11
+ export const LOGIN_HISTORY_WINDOW_DAYS = 30;
12
+
13
+ /** More trusted browsers than this no longer counts as a protection of the account. */
14
+ export const TRUSTED_BROWSERS_MAX = 3;
15
+
6
16
  /** A browser whose logins skip the mailed and texted codes. */
7
17
  export const trustedBrowserSchema = z.object({
8
18
  id: z.number().int().positive(),
@@ -16,6 +26,28 @@ export const trustedBrowserSchema = z.object({
16
26
 
17
27
  export type TrustedBrowser = z.infer<typeof trustedBrowserSchema>;
18
28
 
29
+ /**
30
+ * One successful login of the account, kept so a login from a device that is
31
+ * not the account's can be spotted. Never removed by the account: an intruder
32
+ * must not be able to erase their trace.
33
+ */
34
+ export const loginEntrySchema = z.object({
35
+ id: z.number().int().positive(),
36
+ /** Epoch seconds. */
37
+ at: z.number().int(),
38
+ /** Browser and system, from the user agent (`Firefox sur Linux`). */
39
+ label: z.string(),
40
+ ip: z.string(),
41
+ /** The codes the login went through after the password; none for a trusted browser. */
42
+ steps: z.array(loginStepSchema),
43
+ /** The browser was trusted at the time. */
44
+ trusted: z.boolean(),
45
+ /** The login that opened the session asking. */
46
+ current: z.boolean()
47
+ });
48
+
49
+ export type LoginEntry = z.infer<typeof loginEntrySchema>;
50
+
19
51
  /** The checks a login meets on a browser the account does not know. */
20
52
  export const loginChecksStatusSchema = z.object({
21
53
  email: z.object({
@@ -32,7 +64,9 @@ export const loginChecksStatusSchema = z.object({
32
64
  /** The verified number, masked; `null` without one. */
33
65
  phone: z.string().nullable()
34
66
  }),
35
- browsers: z.array(trustedBrowserSchema)
67
+ browsers: z.array(trustedBrowserSchema),
68
+ /** Successful logins over the last `LOGIN_HISTORY_WINDOW_DAYS` days. */
69
+ recentLogins: z.number().int().nonnegative()
36
70
  });
37
71
 
38
72
  export type LoginChecksStatus = z.infer<typeof loginChecksStatusSchema>;
@@ -9,6 +9,8 @@ import { z } from 'zod';
9
9
  export const STEP_UP_MINUTES_MIN = 1;
10
10
  export const STEP_UP_MINUTES_MAX = 480;
11
11
  export const STEP_UP_MINUTES_DEFAULT = 15;
12
+ /** Asked again after this many minutes or less: short enough to count as a protection. */
13
+ export const STEP_UP_STRICT_MINUTES = 30;
12
14
 
13
15
  export const stepUpStatusSchema = z.object({
14
16
  /** The account has an authenticator app: without one, no machine can be driven. */
@@ -76,14 +76,23 @@ export const userSecuritySchema = z.object({
76
76
  * not exist here and is not counted.
77
77
  */
78
78
  loginConfirmation: z.boolean().nullable(),
79
+ /**
80
+ * Login confirmation is on and at most `TRUSTED_BROWSERS_MAX` browsers
81
+ * skip it. `null` with `loginConfirmation`.
82
+ */
83
+ trustedBrowsers: z.boolean().nullable(),
79
84
  /** TOTP two-factor authentication is enabled. */
80
85
  twoFactor: z.boolean(),
86
+ /**
87
+ * Two-factor is on and the code to drive a machine is asked again after
88
+ * `STEP_UP_STRICT_MINUTES` or less without driving.
89
+ */
90
+ stepUpValidation: z.boolean(),
81
91
  /** Password-based encryption (DEK wrapped by the user's password) is on. */
82
92
  passwordEncryption: z.boolean(),
83
93
  /**
84
- * Password re-validation window is configured to a strict value: enabled and
85
- * short enough (≤ 5 min) to count as a protection. Disabled (0) or a long
86
- * window does not count.
94
+ * Password-based encryption is on and its re-validation window is short
95
+ * enough (5 min or less, 0 being the strongest) to count as a protection.
87
96
  */
88
97
  reAuthValidation: z.boolean()
89
98
  });
@@ -1,5 +1,5 @@
1
1
  import { z } from 'zod';
2
- import { loginChecksStatusSchema } from '../domain/loginChecks';
2
+ import { loginChecksStatusSchema, loginEntrySchema } from '../domain/loginChecks';
3
3
 
4
4
  const output = z.object({ status: loginChecksStatusSchema });
5
5
 
@@ -68,6 +68,26 @@ export const loginChecksForgetBrowsers = {
68
68
  output
69
69
  };
70
70
 
71
+ /**
72
+ * The account's successful logins over the last `LOGIN_HISTORY_WINDOW_DAYS`
73
+ * days, newest first, and how many older ones the history still holds.
74
+ */
75
+ export const loginChecksHistory = {
76
+ command: 'loginChecks.history' as const,
77
+ input: z.object({}),
78
+ output: z.object({ entries: z.array(loginEntrySchema), older: z.number().int().nonnegative() })
79
+ };
80
+
81
+ /**
82
+ * Close every session of the account but the one asking: what to do after
83
+ * spotting a login that is not one's own. Answers how many sessions closed.
84
+ */
85
+ export const loginChecksLogoutOthers = {
86
+ command: 'loginChecks.logoutOthers' as const,
87
+ input: z.object({}),
88
+ output: z.object({ closed: z.number().int().nonnegative() })
89
+ };
90
+
71
91
  export const loginChecksCommands = [
72
92
  loginChecksStatus,
73
93
  loginChecksSetEmail,
@@ -76,5 +96,7 @@ export const loginChecksCommands = [
76
96
  loginChecksPhoneConfirm,
77
97
  loginChecksPhoneRemove,
78
98
  loginChecksForgetBrowser,
79
- loginChecksForgetBrowsers
99
+ loginChecksForgetBrowsers,
100
+ loginChecksHistory,
101
+ loginChecksLogoutOthers
80
102
  ] as const;
@@ -173,7 +173,16 @@ export const agentTargetStatusSchema = z.object({
173
173
  /** Whether the binary is present on the server (greys it out in the UI). */
174
174
  available: z.boolean(),
175
175
  /** Size in bytes when available, else `null`. */
176
- sizeBytes: z.number().int().nonnegative().nullable()
176
+ sizeBytes: z.number().int().nonnegative().nullable(),
177
+ /**
178
+ * SHA-256 of the served binary, from the release manifest: what a user
179
+ * compares before running a binary fetched by hand. `null` when the
180
+ * binary is absent or no manifest names it (a local build).
181
+ */
182
+ sha256: z
183
+ .string()
184
+ .regex(/^[a-f0-9]{64}$/)
185
+ .nullable()
177
186
  });
178
187
 
179
188
  export type AgentTargetStatus = z.infer<typeof agentTargetStatusSchema>;
package/src/index.ts CHANGED
@@ -905,16 +905,21 @@ export {
905
905
  STEP_UP_MINUTES_DEFAULT,
906
906
  STEP_UP_MINUTES_MAX,
907
907
  STEP_UP_MINUTES_MIN,
908
+ STEP_UP_STRICT_MINUTES,
908
909
  stepUpRequiredDetailsSchema,
909
910
  stepUpStatusSchema
910
911
  } from './domain/stepUp';
911
912
  export type { StepUpRequiredDetails, StepUpStatus } from './domain/stepUp';
912
913
  export {
914
+ LOGIN_HISTORY_DAYS,
915
+ LOGIN_HISTORY_WINDOW_DAYS,
913
916
  loginChecksStatusSchema,
917
+ loginEntrySchema,
914
918
  TRUSTED_BROWSER_DAYS,
919
+ TRUSTED_BROWSERS_MAX,
915
920
  trustedBrowserSchema
916
921
  } from './domain/loginChecks';
917
- export type { LoginChecksStatus, TrustedBrowser } from './domain/loginChecks';
922
+ export type { LoginChecksStatus, LoginEntry, TrustedBrowser } from './domain/loginChecks';
918
923
  export type {
919
924
  BackupCodeRow,
920
925
  TwoFactorRow,
@@ -1123,6 +1128,8 @@ export {
1123
1128
  loginChecksCommands,
1124
1129
  loginChecksForgetBrowser,
1125
1130
  loginChecksForgetBrowsers,
1131
+ loginChecksHistory,
1132
+ loginChecksLogoutOthers,
1126
1133
  loginChecksPhoneConfirm,
1127
1134
  loginChecksPhoneRemove,
1128
1135
  loginChecksPhoneStart,
@@ -581,16 +581,27 @@ declare module 'deveye-sdk-client' {
581
581
  export const ReadOnlyNotice: ComponentType<{ children: ReactNode }>;
582
582
  export interface ErrorNoteInput {
583
583
  message: string;
584
+ /** The failure's code, `null` when it carries none: it decides whether a report is offered. */
584
585
  code: string | null;
585
586
  }
586
587
  export interface ErrorNoteProps {
587
588
  note: ErrorNoteInput | null;
589
+ /** The caller's repair actions (retry, open settings), before the report button. */
588
590
  children?: ReactNode;
591
+ /** Makes the banner dismissible: the close button comes last, after the report button. */
592
+ onDismiss?: () => void;
593
+ /**
594
+ * Keeps the banner where it is written instead of the frame's slot: the
595
+ * failure of one row among others (a history entry, an upload).
596
+ */
597
+ inline?: boolean;
589
598
  }
590
599
  /**
591
600
  * A refusal banner: the sentence, the caller's own repair actions as
592
601
  * children, and a report button when the failure is not one the user can
593
- * fix on their own.
602
+ * fix on their own. Wherever you write it, it shows at the top of its
603
+ * frame, full width: under your view's `StickyHeader`, under a dialog's
604
+ * title. Without either, it stays in place.
594
605
  */
595
606
  export const ErrorNote: ComponentType<ErrorNoteProps>;
596
607
  /** Open the report form, primed with what failed. */
@@ -651,10 +662,16 @@ declare module 'deveye-sdk-client' {
651
662
  done: Promise<void>;
652
663
  abort(): void;
653
664
  }
654
- /** What `UploadHandle.done` rejects with: the server's message, or why the connection ended. */
665
+ /**
666
+ * What `UploadHandle.done` rejects with: the server's message (`{ message }`
667
+ * in your route's error body), or why the connection ended. `code` is the
668
+ * protocol code the HTTP status maps to (409 `conflict`, 413 `validation`,
669
+ * 5xx `internal`, a dropped connection `network`), `null` once aborted.
670
+ */
655
671
  export class UploadError extends Error {
672
+ readonly code: string | null;
656
673
  readonly aborted: boolean;
657
- constructor(message: string, aborted?: boolean);
674
+ constructor(message: string, code: string | null, aborted?: boolean);
658
675
  }
659
676
  /**
660
677
  * POSTs the file as is (`application/octet-stream`) to a route of yours,
@@ -764,12 +781,18 @@ declare module 'deveye-sdk-client' {
764
781
  load: () => Promise<T>,
765
782
  fallback: string,
766
783
  deps?: readonly unknown[]
767
- ): { data: T | null; error: string | null; loading: boolean; reload: () => void };
784
+ ): { data: T | null; error: ErrorNoteInput | null; loading: boolean; reload: () => void };
768
785
  export function invalidate(...keys: ExternalResourceKey[]): void;
769
786
  export function useResourceVersion(key: ExternalResourceKey): number;
770
787
  /** Imperative subscription to one resource key's invalidations. Returns the unsubscribe. */
771
788
  export function onResourceChange(key: ExternalResourceKey, cb: () => void): () => void;
772
789
  export function humanizeError(error: unknown, fallback: string): string;
790
+ /**
791
+ * A failure as `ErrorNote` shows it: the `humanizeError` sentence and the
792
+ * code, read off the error's shape. What every failure shown to the user
793
+ * goes through, so that one nobody can fix offers a report.
794
+ */
795
+ export function errorNote(error: unknown, fallback: string): ErrorNoteInput;
773
796
  /** The error a command rejects with: the server's code (or the socket's), its message, and the validation details when any. */
774
797
  export class WsError extends Error {
775
798
  constructor(code: string, message: string, details?: unknown);
@@ -845,9 +868,12 @@ declare module 'deveye-sdk-client' {
845
868
  /**
846
869
  * The rejection of `ensureSecrecyUnlocked` / `withSecrecy` when the user
847
870
  * dismisses the unlock prompt: a deliberate cancel, not a failure (close a
848
- * view that has nothing to show, rather than reporting an error).
871
+ * view that has nothing to show, rather than reporting an error). Coded
872
+ * `locked`: `errorNote` reads it as a refusal, and offers no report.
849
873
  */
850
- export class UnlockCancelledError extends Error {}
874
+ export class UnlockCancelledError extends Error {
875
+ readonly code: 'locked';
876
+ }
851
877
 
852
878
  // ── Live ───────────────────────────────────────────────────────────────
853
879
  export type LiveSegmentKind = 'view' | 'l1' | 'l2' | 'l3' | 'l4';
@@ -923,7 +949,7 @@ declare module 'deveye-sdk-client' {
923
949
  load: (() => Promise<readonly DeviceRelayOption[]>) | null
924
950
  ): {
925
951
  devices: readonly DeviceRelayOption[];
926
- error: string | null;
952
+ error: ErrorNoteInput | null;
927
953
  };
928
954
  /** One rule of a `PathExclusionsEditor`. */
929
955
  export interface PathExclusionItem {
@@ -931,13 +957,20 @@ declare module 'deveye-sdk-client' {
931
957
  kind: PathExclusionKind;
932
958
  pattern: string;
933
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
+ }
934
965
  /**
935
966
  * The exclusions of a walked folder (a CloudSync share, a backed-up
936
967
  * folder): exact path, component name or regex, relative to its root,
937
968
  * validated the way the agent will run them. `onAdd` gets a rule already
938
969
  * validated; `false` or a rejection keeps what was typed (say why where
939
970
  * you show your errors). `scope` ends the suggestions' tooltip ("le
940
- * 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).
941
974
  */
942
975
  export const PathExclusionsEditor: ComponentType<{
943
976
  items: readonly PathExclusionItem[];
@@ -946,6 +979,8 @@ declare module 'deveye-sdk-client' {
946
979
  canWrite: boolean;
947
980
  scope: string;
948
981
  disabled?: boolean;
982
+ found?: readonly PathExclusionFound[];
983
+ onAddFound?: (name: string) => boolean | Promise<boolean>;
949
984
  }>;
950
985
  /**
951
986
  * The workspace's enrolled devices, live: what the Devices module offers
@@ -1105,7 +1140,7 @@ declare module 'deveye-sdk-client' {
1105
1140
  export function useDomains(feature: FeatureId): {
1106
1141
  domains: readonly FeatureDomain[];
1107
1142
  loading: boolean;
1108
- error: string | null;
1143
+ error: ErrorNoteInput | null;
1109
1144
  };
1110
1145
  /**
1111
1146
  * A member's identity dot: their avatar, or the default picture until they
@@ -1142,7 +1177,11 @@ declare module 'deveye-sdk-client' {
1142
1177
  /** Image inputs accepted by `fileToSquareDataUrl`. */
1143
1178
  export const ACCEPTED_TYPES: readonly string[];
1144
1179
  export const MAX_INPUT_BYTES: number;
1145
- /** A picked image, resized to a square data URL under `maxLength` characters; throws a readable message. */
1180
+ /**
1181
+ * A picked image, resized to a square data URL under `maxLength`
1182
+ * characters. A file it cannot use throws an error coded `validation`
1183
+ * whose message is readable: `errorNote` shows it as is.
1184
+ */
1146
1185
  export function fileToSquareDataUrl(
1147
1186
  file: File,
1148
1187
  opts: { size: number; maxLength: number }
@@ -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
  }
@@ -936,3 +936,79 @@ export interface AccountPlanProvider {
936
936
  /** `fresh`: never from a cache, the host is about to pause or resume on the answer. */
937
937
  planFor(userId: number, opts?: { fresh?: boolean }): Promise<AccountPlan>;
938
938
  }
939
+
940
+ /**
941
+ * Key under `FeatureService.providers` of the automatic moderation: the
942
+ * instance's lists of banned content (file fingerprints and name patterns),
943
+ * kept by the moderation module and consulted by every feature that stores or
944
+ * publishes files (Hosting, CloudSync). Absent (module not installed), nothing
945
+ * is checked and the features behave as before: the caller degrades to
946
+ * "no hit".
947
+ */
948
+ export const MODERATION_PROVIDER = 'moderation.check' as const;
949
+
950
+ /** Why a content is banned, in the vocabulary of the public report forms. */
951
+ export const MODERATION_REASONS = [
952
+ 'illegal',
953
+ 'copyright',
954
+ 'malware',
955
+ 'privacy',
956
+ 'minors',
957
+ 'other'
958
+ ] as const;
959
+ export type ModerationReason = (typeof MODERATION_REASONS)[number];
960
+
961
+ /**
962
+ * Where the content goes: `public` when anyone with an address can download it
963
+ * (a Hosting folder), `private` when it stays with its owner and their devices
964
+ * (a CloudSync share). A rule says which exposures it covers.
965
+ */
966
+ export type ModerationExposure = 'public' | 'private';
967
+
968
+ export interface ModerationSubject {
969
+ /** The lowercase hex SHA-256 of the plaintext; `null` when the host cannot compute it (end-to-end encrypted content). */
970
+ sha256: string | null;
971
+ /** The file name as the user named it, without its folders. */
972
+ name: string;
973
+ exposure: ModerationExposure;
974
+ /** For the moderators' journal: who sent what, and where. */
975
+ origin: {
976
+ /** The feature's id (`x-hosting`, `cloudsync`). */
977
+ feature: string;
978
+ workspaceId: number | null;
979
+ /** `null` for a transfer a device drives without a session. */
980
+ userId: number | null;
981
+ /** The item the file belongs to (a folder's name, a share's name), as the moderators read it. */
982
+ context: string;
983
+ };
984
+ size?: number;
985
+ }
986
+
987
+ export interface ModerationHit {
988
+ ruleId: number;
989
+ kind: 'fingerprint' | 'name';
990
+ reason: ModerationReason;
991
+ /** What the user is told, one sentence: "Logiciel malveillant connu". */
992
+ label: string;
993
+ }
994
+
995
+ export interface ModerationProvider {
996
+ /**
997
+ * `null` when nothing matches. A hit is recorded for the moderators
998
+ * (feature, context, name, account) before it is returned; the caller
999
+ * decides what becomes of the content: hold it, refuse it.
1000
+ */
1001
+ check(subject: ModerationSubject): Promise<ModerationHit | null>;
1002
+ /**
1003
+ * Bans these fingerprints from now on (after a takedown): the ones already
1004
+ * banned are left as they are. Returns how many were added. Nothing already
1005
+ * stored is re-examined.
1006
+ */
1007
+ ban(input: {
1008
+ fingerprints: readonly string[];
1009
+ reason: ModerationReason;
1010
+ label: string;
1011
+ /** The moderator's account, `null` for the instance. */
1012
+ by: number | null;
1013
+ }): Promise<number>;
1014
+ }
package/src/sdk/server.ts CHANGED
@@ -251,6 +251,17 @@ export interface SdkAlert {
251
251
  embeds?: readonly Record<string, unknown>[];
252
252
  }
253
253
 
254
+ /** An alert for the instance's administrators, see `FeatureServiceDeps.alertInstance`. */
255
+ export interface SdkInstanceAlert {
256
+ /** Groups repeats: one alert per key every ten minutes at most. */
257
+ key: string;
258
+ /** `resolved` announces a return to normal. */
259
+ level: 'info' | 'resolved' | 'error' | 'critical';
260
+ title: string;
261
+ /** Rendered as a code block: a message, a path, a date. */
262
+ detail?: string;
263
+ }
264
+
254
265
  /** A routed channel that can carry a live message (see `notify.liveChannels`). */
255
266
  export interface SdkLiveChannel {
256
267
  id: number;
@@ -1716,6 +1727,14 @@ export interface FeatureServiceDeps<Repo = unknown> {
1716
1727
  domains: SdkFleetDomains;
1717
1728
  /** The named contracts the host holds, see `SdkProviders`. */
1718
1729
  providers: SdkProviders;
1730
+ /**
1731
+ * Alerts the instance's administrators on their `system` channels, for
1732
+ * what the INSTANCE must fix (its configuration, a certificate it serves),
1733
+ * never for one user's trouble: that goes to `deveyeFor(ws).notify`. The
1734
+ * host prefixes `key` with your feature id; nothing leaves outside
1735
+ * production. Log the cause as well: the alert is not a log.
1736
+ */
1737
+ alertInstance(alert: SdkInstanceAlert): void;
1719
1738
  /**
1720
1739
  * The app's standard loop: setInterval + reentrancy guard + unref, the
1721
1740
  * exact pattern of every native service. Use it instead of rolling your own.
@@ -26,6 +26,7 @@ import {
26
26
  type SdkCipher,
27
27
  type SdkDevice,
28
28
  type SdkFeatureContext,
29
+ type SdkInstanceAlert,
29
30
  type SdkLogger,
30
31
  type SdkObjectStore,
31
32
  type SdkOrigins,
@@ -778,6 +779,8 @@ export interface RecordedServiceCalls extends RecordedCalls {
778
779
  liveTopicChanges: { workspaceId: number; topics: readonly string[] }[];
779
780
  /** Emails `accountMail.send` and `sendToModerators` accepted, with the address they went to. */
780
781
  mails: { userId: number; to: string; message: SdkAccountMailMessage }[];
782
+ /** What `alertInstance` raised, in order, keys as the module gave them. */
783
+ instanceAlerts: SdkInstanceAlert[];
781
784
  }
782
785
 
783
786
  export interface TestServiceDeps<Repo> extends FeatureServiceDeps<Repo> {
@@ -859,7 +862,8 @@ export function createTestServiceDeps<Repo = undefined>(
859
862
  tickers: [],
860
863
  liveChanges: [],
861
864
  liveTopicChanges: [],
862
- mails: []
865
+ mails: [],
866
+ instanceAlerts: []
863
867
  };
864
868
  const stores = new Map<number, TestFeatureStore>();
865
869
  const sealedBytes = new Map<string, Uint8Array>();
@@ -1069,6 +1073,9 @@ export function createTestServiceDeps<Repo = undefined>(
1069
1073
  )
1070
1074
  },
1071
1075
  providers: fakeProviders(overrides.providers ?? {}),
1076
+ alertInstance(alert) {
1077
+ recorded.instanceAlerts.push(alert);
1078
+ },
1072
1079
  createTicker({ intervalMs, tick }) {
1073
1080
  recorded.tickers.push({ intervalMs, tick });
1074
1081
  return { start: () => undefined, stop: () => undefined };