@deveye/types 0.18.2 → 0.19.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/src/sdk/client.ts CHANGED
@@ -42,6 +42,15 @@ export interface FeatureViewProps {
42
42
  closeFeature(): void;
43
43
  }
44
44
 
45
+ /** Props of {@link FeatureClient.AccountView}. */
46
+ export interface AccountViewProps {
47
+ close(): void;
48
+ /** The viewer is a global administrator of this DevEye. */
49
+ isAdmin: boolean;
50
+ /** The hint a sign-up carried (`manifest.accountEntry.signupHint`), delivered once. */
51
+ hint?: string;
52
+ }
53
+
45
54
  /**
46
55
  * Your package's `./client` export.
47
56
  */
@@ -51,9 +60,11 @@ export interface FeatureClient {
51
60
  * data comes from `useResource`, so the card and the full view share one
52
61
  * cache and refresh together.
53
62
  */
54
- Widget: ComponentType;
55
- /** The full view, opened when the card expands. */
56
- Full: ComponentType<FeatureViewProps>;
63
+ Widget?: ComponentType;
64
+ /** The full view, opened when the card expands. Required with `Widget` unless `manifest.accountOnly`. */
65
+ Full?: ComponentType<FeatureViewProps>;
66
+ /** The view `manifest.accountEntry` opens from the user menu. */
67
+ AccountView?: ComponentType<AccountViewProps>;
57
68
  /**
58
69
  * The vignette shown on your card in the home grid's add market and on
59
70
  * your "About" sheet. Without one, the host draws a neutral module mark:
@@ -102,6 +113,38 @@ export interface FeatureClient {
102
113
  * Deliberately a subset of the module's own contract: what a linked-service
103
114
  * block needs, and nothing the module may want to change later.
104
115
  */
116
+ /**
117
+ * One figure of a project's dashboard tile. The module formats it, the host only
118
+ * places it: neither has to know the other's vocabulary.
119
+ */
120
+ export interface SdkTileMetric {
121
+ /** Stable key of the figure inside its tile, so the host never orders by accident. */
122
+ key: string;
123
+ label: string;
124
+ /** Already formatted by the module (« 1 240 », « 99,95 % », « il y a 3 h »). */
125
+ value: string;
126
+ /** What the theme must say of this value. Never a colour. */
127
+ tone?: 'neutral' | 'accent' | 'good' | 'warn' | 'bad';
128
+ }
129
+
130
+ /**
131
+ * What a module answers about ONE of its items, for a dashboard tile. Always one
132
+ * entry per id asked for, so the host never has to guess which one is missing.
133
+ */
134
+ export interface SdkTileSummary {
135
+ itemId: number;
136
+ /** The item's name; the host makes it the tile's heading. */
137
+ title: string;
138
+ /** Two or three figures, never more: a tile is not a screen. */
139
+ metrics: readonly SdkTileMetric[];
140
+ /**
141
+ * Why it cannot be measured, in one sentence (item gone, token revoked,
142
+ * monitoring off). The host shows it inside the tile and does NOT turn it
143
+ * into a screen error: a dashboard shows what it can.
144
+ */
145
+ unavailable?: string;
146
+ }
147
+
105
148
  export interface UptimeLinkedService {
106
149
  id: number;
107
150
  name: string;
@@ -160,6 +203,13 @@ export interface SdkDeviceSummary {
160
203
  export interface UptimeClientProvider {
161
204
  /** The workspace's services, as `uptime.list` returns them. */
162
205
  listServices(): Promise<readonly UptimeLinkedService[]>;
206
+ /**
207
+ * The given services, summarised for a project's dashboard tile. ONE round
208
+ * trip whatever their number: a dashboard that opened one per tile would
209
+ * cost far more than the figures are worth. An id the caller cannot read,
210
+ * or that is gone, comes back `unavailable`, never as a throw.
211
+ */
212
+ summarize(serviceIds: readonly number[]): Promise<readonly SdkTileSummary[]>;
163
213
  /**
164
214
  * A service's history for the strip. `stamp` is what re-reads it (pass
165
215
  * `service.lastCheckedAt`); no timer.
@@ -215,6 +265,13 @@ export interface DatabaseLinkedCandidate {
215
265
  export interface DatabaseClientProvider {
216
266
  /** The workspace's databases, as `database.list` returns them. */
217
267
  listDatabases(): Promise<readonly DatabaseLinkedCandidate[]>;
268
+ /**
269
+ * The given databases, summarised for a project's dashboard tile. ONE round
270
+ * trip whatever their number: a dashboard that opened one per tile would
271
+ * cost far more than the figures are worth. An id the caller cannot read,
272
+ * or that is gone, comes back `unavailable`, never as a throw.
273
+ */
274
+ summarize(databaseIds: readonly number[]): Promise<readonly SdkTileSummary[]>;
218
275
  /**
219
276
  * A database linked to a project, shown in full: header (name, address,
220
277
  * actions, its own settings button), state, alerts, table explorer. Loads
@@ -252,6 +309,13 @@ export interface DeployLinkedCandidate {
252
309
  export interface DeployClientProvider {
253
310
  /** The workspace's targets, as `deploy.list` returns them. */
254
311
  listTargets(): Promise<readonly DeployLinkedCandidate[]>;
312
+ /**
313
+ * The given targets, summarised for a project's dashboard tile. ONE round
314
+ * trip whatever their number: a dashboard that opened one per tile would
315
+ * cost far more than the figures are worth. An id the caller cannot read,
316
+ * or that is gone, comes back `unavailable`, never as a throw.
317
+ */
318
+ summarize(targetIds: readonly number[]): Promise<readonly SdkTileSummary[]>;
255
319
  /**
256
320
  * A target linked to a project, shown in full: identity, last deployment,
257
321
  * trigger, its own settings button. Loads itself by `deploy.get`, follows
@@ -292,6 +356,13 @@ export interface GitLinkedCandidate {
292
356
  export interface GitClientProvider {
293
357
  /** The workspace's repositories, as `git.repoList` returns them. */
294
358
  listRepos(): Promise<readonly GitLinkedCandidate[]>;
359
+ /**
360
+ * The given repositories, summarised for a project's dashboard tile. ONE round
361
+ * trip whatever their number: a dashboard that opened one per tile would
362
+ * cost far more than the figures are worth. An id the caller cannot read,
363
+ * or that is gone, comes back `unavailable`, never as a throw.
364
+ */
365
+ summarize(repoIds: readonly number[]): Promise<readonly SdkTileSummary[]>;
295
366
  /**
296
367
  * A repository linked to a project, shown in full: header (name, sync
297
368
  * state, actions, its own settings button), graph and panels. Loads
@@ -323,6 +394,13 @@ export interface AudienceLinkedCandidate {
323
394
  export interface AudienceClientProvider {
324
395
  /** The workspace's sites, as `audience.list` returns them. */
325
396
  listSites(): Promise<readonly AudienceLinkedCandidate[]>;
397
+ /**
398
+ * The given sites, summarised for a project's dashboard tile. ONE round
399
+ * trip whatever their number: a dashboard that opened one per tile would
400
+ * cost far more than the figures are worth. An id the caller cannot read,
401
+ * or that is gone, comes back `unavailable`, never as a throw.
402
+ */
403
+ summarize(siteIds: readonly number[]): Promise<readonly SdkTileSummary[]>;
326
404
  /**
327
405
  * A site linked to a project, shown in full: its sticky heading, actions
328
406
  * (install, its own settings button), stats, funnels. Loads itself by
@@ -343,13 +421,33 @@ export interface AudienceClientProvider {
343
421
  * the ready senders (open tier, enabled) an email notification channel picks
344
422
  * from, and the feature's own account dialog.
345
423
  */
424
+ /** What a caller already knows of the mailbox it sends to Mail's account form. */
425
+ export interface MailAccountPrefill {
426
+ displayName: string;
427
+ emailAddress: string;
428
+ imap: { host: string; port: number; username: string; password: string };
429
+ smtp: { host: string; port: number; username: string; password: string };
430
+ }
431
+
346
432
  export interface MailClientProvider {
347
433
  /** The workspace's ready senders, as the module lists them. */
348
434
  listSenders(): Promise<readonly { id: number; label: string; address: string }[]>;
435
+ /**
436
+ * The account holding this address among those the caller can read, or
437
+ * null. A guarded account of a locked session does not show its address:
438
+ * it reads as absent.
439
+ */
440
+ findByAddress(address: string): Promise<{ id: number } | null>;
349
441
  /**
350
442
  * The feature's account form (manual connection or OAuth consent), to
351
443
  * declare a mailbox from the channel form. `onSaved` fires when a mailbox
352
- * came out of it; the host re-lists to find which.
444
+ * came out of it; the host re-lists to find which. With `prefill`, the
445
+ * form opens on the manual connection, filled in and ready to save.
353
446
  */
354
- AccountDialog: ComponentType<{ open: boolean; onClose: () => void; onSaved: () => void }>;
447
+ AccountDialog: ComponentType<{
448
+ open: boolean;
449
+ onClose: () => void;
450
+ onSaved: () => void;
451
+ prefill?: MailAccountPrefill;
452
+ }>;
355
453
  }
@@ -0,0 +1,30 @@
1
+ import assert from 'node:assert/strict';
2
+ import { test } from 'node:test';
3
+
4
+ import { DOMAIN_HOST_PATTERN, domainOwnershipRecord, normaliseDomainHost } from './domains';
5
+
6
+ test('normaliseDomainHost drops case, port and trailing dots', () => {
7
+ assert.equal(normaliseDomainHost(' Rdv.Example.COM:8443 '), 'rdv.example.com');
8
+ assert.equal(normaliseDomainHost('example.com..'), 'example.com');
9
+ });
10
+
11
+ test('DOMAIN_HOST_PATTERN wants at least two plain labels', () => {
12
+ assert.ok(DOMAIN_HOST_PATTERN.test('mail.example.com'));
13
+ assert.ok(DOMAIN_HOST_PATTERN.test('xn--bcher-kva.example'));
14
+ assert.ok(!DOMAIN_HOST_PATTERN.test('localhost'));
15
+ assert.ok(!DOMAIN_HOST_PATTERN.test('exa mple.com'));
16
+ assert.ok(!DOMAIN_HOST_PATTERN.test('https://example.com'));
17
+ assert.ok(!DOMAIN_HOST_PATTERN.test(`${'a'.repeat(64)}.com`));
18
+ });
19
+
20
+ test('the ownership record names the feature by its slug', () => {
21
+ assert.deepEqual(domainOwnershipRecord('x-rdv', 'example.com', 'abc'), {
22
+ type: 'TXT',
23
+ name: '_deveye.example.com',
24
+ value: 'deveye-rdv=abc'
25
+ });
26
+ assert.equal(
27
+ domainOwnershipRecord('mailserver', 'example.com', 'abc').value,
28
+ 'deveye-mailserver=abc'
29
+ );
30
+ });
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Domain names a feature serves under: the pure half, shared by the server
3
+ * contract, the app and the test harness. No I/O here.
4
+ */
5
+ import type { DnsRecord } from '../domain/featureDomain';
6
+
7
+ export type SdkDnsRecord = DnsRecord;
8
+
9
+ /** A bare host name: labels of letters, digits and hyphens, at least two. Punycode passes as is. */
10
+ export const DOMAIN_HOST_PATTERN = /^(?=.{1,253}$)[a-z0-9-]{1,63}(\.[a-z0-9-]{1,63})+$/;
11
+
12
+ /** Lowercase, port and trailing dots dropped. Accepts a raw `Host` header. */
13
+ export function normaliseDomainHost(raw: string): string {
14
+ return raw.trim().toLowerCase().split(':')[0].replace(/\.+$/, '');
15
+ }
16
+
17
+ /**
18
+ * The ownership proof DevEye checks itself: `_deveye.<host>` holding
19
+ * `deveye-<slug>=<token>`, the slug being the feature id without its `x-`.
20
+ * Several features can prove the same host: each adds its own value.
21
+ */
22
+ export function domainOwnershipRecord(
23
+ featureId: string,
24
+ host: string,
25
+ token: string
26
+ ): SdkDnsRecord {
27
+ const slug = featureId.replace(/^x-/, '');
28
+ return { type: 'TXT', name: `_deveye.${host}`, value: `deveye-${slug}=${token}` };
29
+ }
@@ -100,3 +100,63 @@ test('resolveExtras: the owner holds everything, a member what the grant says, u
100
100
  assert.equal(owner.extraValue('reset'), '');
101
101
  assert.equal(resolveExtras(undefined, true, { reset: true }).canExtra('reset'), false);
102
102
  });
103
+
104
+ test('validateManifest ties the domains tab to the domains field', () => {
105
+ const domains = { hint: 'Your own names.', service: 'Point the name here.' };
106
+ assert.doesNotThrow(() =>
107
+ validateManifest({ ...base, domains, settings: { feature: ['domains'] } })
108
+ );
109
+ assert.throws(
110
+ () => validateManifest({ ...base, settings: { feature: ['domains'] } }),
111
+ /domains tab requires domains/
112
+ );
113
+ assert.throws(
114
+ () =>
115
+ validateManifest({
116
+ ...base,
117
+ hasItems: true,
118
+ itemNoun: 'thing',
119
+ domains,
120
+ settings: { item: ['domains'] }
121
+ }),
122
+ /feature-scope/
123
+ );
124
+ assert.throws(
125
+ () => validateManifest({ ...base, domains: { ...domains, service: ' ' } }),
126
+ /empty service/
127
+ );
128
+ });
129
+
130
+ test('validateManifest refuses a tab id it does not know', () => {
131
+ assert.throws(
132
+ () => validateManifest({ ...base, settings: { feature: ['nope' as 'general'] } }),
133
+ /unknown settings tab/
134
+ );
135
+ });
136
+
137
+ test('validateManifest checks quotas and the account entry', () => {
138
+ const rejects = (patch: Partial<FeatureManifest>, fragment: string) =>
139
+ assert.throws(() => validateManifest({ ...base, ...patch }), new RegExp(fragment));
140
+ assert.doesNotThrow(() =>
141
+ validateManifest({
142
+ ...base,
143
+ quotas: [{ key: 'monitors', label: 'monitors' }],
144
+ accountEntry: { label: 'Subscription' },
145
+ accountOnly: true
146
+ })
147
+ );
148
+ rejects({ quotas: [{ key: 'Bad key', label: 'x' }] }, 'invalid quota key');
149
+ rejects(
150
+ {
151
+ quotas: [
152
+ { key: 'monitors', label: 'a' },
153
+ { key: 'monitors', label: 'b' }
154
+ ]
155
+ },
156
+ 'duplicate quota key'
157
+ );
158
+ rejects({ quotas: [{ key: 'monitors', label: ' ' }] }, 'empty label');
159
+ rejects({ accountOnly: true }, 'accountOnly requires accountEntry');
160
+ rejects({ accountOnly: true, accountEntry: { label: 'S' }, tile: {} }, 'no tile');
161
+ rejects({ accountEntry: { label: ' ' } }, 'requires a label');
162
+ });
@@ -59,6 +59,23 @@ export type ExtraPermissionSpec =
59
59
  ownerValue: string;
60
60
  };
61
61
 
62
+ /** Hard cap on `quotas`. */
63
+ export const MAX_FEATURE_QUOTAS = 8;
64
+
65
+ /**
66
+ * Something your feature creates that an account plan may bound (monitors,
67
+ * paired agents). You count, the host decides: see `SdkQuota`. Without a plan
68
+ * provider installed (a self-hosted DevEye), every quota is unlimited.
69
+ */
70
+ export interface FeatureQuotaSpec {
71
+ /** Same shape as an extra permission key. The plan names it `<featureId>.<key>`. */
72
+ key: string;
73
+ /** Plural noun, as a limit reads: "5 monitors". For `bytes`, what is measured: "of storage". */
74
+ label: string;
75
+ /** What the number counts. `bytes`: the host writes the limit as a size ("1 GB"). Default: things. */
76
+ unit?: 'bytes';
77
+ }
78
+
62
79
  /** Hard cap on `extraPermissions`: keeps role editors legible. */
63
80
  export const MAX_EXTRA_PERMISSIONS = 10;
64
81
 
@@ -107,12 +124,20 @@ export type NativeCapability =
107
124
  * of your own. Declared, because it lets a module put bytes on someone
108
125
  * else's socket without them asking. See `SdkLive.publish`.
109
126
  */
110
- | 'live.publish';
127
+ | 'live.publish'
128
+ /**
129
+ * Read accounts (id, email, username, creation date): the caller's own in a
130
+ * handler, any account from a service. For what belongs to an account and
131
+ * not to a workspace (a subscription, a receipt to address).
132
+ */
133
+ | 'accounts.read';
111
134
 
112
135
  /**
113
136
  * Settings tabs the shell can render for you.
114
- * - `'notifications'` and `'permissions'` are fully generic: DevEye renders
115
- * them from the manifest alone, you write no component.
137
+ * - `'notifications'`, `'permissions'` and `'domains'` are fully generic:
138
+ * DevEye renders them from the manifest alone, you write no component.
139
+ * `'domains'` (feature scope only) needs the manifest's `domains` and a
140
+ * `domains` entry on the server side.
116
141
  * - `'general'`, `'sources'`, `'sync'` and `'encryption'` need a panel
117
142
  * component, provided by your client entry (`settingsPanels`), keyed by
118
143
  * the tab id. `'sync'` (item scope only) is the cadence and maintenance of
@@ -122,7 +147,7 @@ export type NativeCapability =
122
147
  * places the tab, the module owns the choice.
123
148
  */
124
149
  export type SettingsTab =
125
- 'general' | 'sources' | 'notifications' | 'permissions' | 'sync' | 'encryption';
150
+ 'general' | 'sources' | 'domains' | 'notifications' | 'permissions' | 'sync' | 'encryption';
126
151
 
127
152
  /** A custom settings tab. Needs a matching panel in `settingsPanels`. */
128
153
  export interface CustomTabRef {
@@ -144,6 +169,7 @@ const CUSTOM_TAB_PATTERN = /^[a-z][a-z0-9]{1,23}$/;
144
169
  const BUILTIN_TABS: readonly string[] = [
145
170
  'general',
146
171
  'sources',
172
+ 'domains',
147
173
  'notifications',
148
174
  'permissions',
149
175
  'sync',
@@ -151,6 +177,9 @@ const BUILTIN_TABS: readonly string[] = [
151
177
  'sharing'
152
178
  ];
153
179
 
180
+ /** The built-in ids a manifest may list: `sharing` is the shell's alone. */
181
+ const DECLARABLE_TABS: readonly string[] = BUILTIN_TABS.filter((id) => id !== 'sharing');
182
+
154
183
  /** See {@link FeatureManifest.alsoInvalidatedBy}. */
155
184
  export interface CrossTopicInvalidation {
156
185
  /** A NATIVE live topic that is not this feature's own. */
@@ -207,6 +236,22 @@ export interface FeatureManifest<Id extends FeatureId = FeatureId> {
207
236
  itemNounGender?: 'm' | 'f';
208
237
  /** Feature-scope reusable settings (API keys, destinations). Opens the Sources tab. */
209
238
  sources?: { hint: string };
239
+ /**
240
+ * The feature serves something under domain names the workspace owns (a
241
+ * public page, a mailbox). Opens the Domains tab, which DevEye renders:
242
+ * declaring, the DNS records to publish, verification. Commits the server
243
+ * entry to `domains` (`FeatureDomainsEntry`).
244
+ */
245
+ domains?: {
246
+ /** Lead sentence of the tab. */
247
+ hint: string;
248
+ /** The one sentence of the second step: how the domain gets wired to what you serve. */
249
+ service: string;
250
+ /** Placeholder of the host field. */
251
+ placeholder?: string;
252
+ /** Warning of the removal confirm when items designate the domain. */
253
+ removal?: string;
254
+ };
210
255
  /**
211
256
  * Whether an item can be projected into another workspace. Decided by
212
257
  * encryption: only the open tier is readable by the server alone. Anything
@@ -236,6 +281,23 @@ export interface FeatureManifest<Id extends FeatureId = FeatureId> {
236
281
  extraPermissions?: readonly ExtraPermissionSpec[];
237
282
  /** See {@link NativeCapability}. */
238
283
  nativeCapabilities?: readonly NativeCapability[];
284
+ /** See {@link FeatureQuotaSpec}. At most {@link MAX_FEATURE_QUOTAS}. */
285
+ quotas?: readonly FeatureQuotaSpec[];
286
+
287
+ /**
288
+ * An entry of the user menu, under "Security", drawn with the module's
289
+ * `icon` and opening `FeatureClient.AccountView`. For what belongs to the
290
+ * account, whatever the active workspace. `signupHint`: the view opens by itself right after
291
+ * a sign-up that carried a hint (`/signup?plan=…`), and receives it. One
292
+ * installed module at most may ask for it.
293
+ */
294
+ accountEntry?: { label: string; signupHint?: boolean };
295
+ /**
296
+ * The module lives in the user menu only: no card, no row in the roles
297
+ * screen, `Widget` and `Full` not required. Requires `accountEntry`, no
298
+ * items, and every command scoped to the account (`access.scope`).
299
+ */
300
+ accountOnly?: boolean;
239
301
 
240
302
  /**
241
303
  * Resource keys this feature owns, `<id>.<name>` (by convention, the
@@ -366,6 +428,25 @@ export function validateManifest(m: FeatureManifest): void {
366
428
  }
367
429
  }
368
430
 
431
+ const quotas = m.quotas ?? [];
432
+ if (quotas.length > MAX_FEATURE_QUOTAS) fail(m.id, `more than ${MAX_FEATURE_QUOTAS} quotas`);
433
+ const quotaKeys = new Set<string>();
434
+ for (const quota of quotas) {
435
+ if (!EXTRA_KEY_PATTERN.test(quota.key)) fail(m.id, `invalid quota key « ${quota.key} »`);
436
+ if (quotaKeys.has(quota.key)) fail(m.id, `duplicate quota key « ${quota.key} »`);
437
+ quotaKeys.add(quota.key);
438
+ if (!quota.label.trim()) fail(m.id, `quota « ${quota.key} »: empty label`);
439
+ }
440
+
441
+ if (m.accountEntry && !m.accountEntry.label.trim()) fail(m.id, 'accountEntry requires a label');
442
+ if (m.accountOnly) {
443
+ if (!m.accountEntry) fail(m.id, 'accountOnly requires accountEntry');
444
+ if (m.hasItems) fail(m.id, 'accountOnly modules own no items');
445
+ if (m.tile || m.topbarWidget || m.settings) {
446
+ fail(m.id, 'accountOnly modules have no tile, topbar widget or settings');
447
+ }
448
+ }
449
+
369
450
  const extras = m.extraPermissions ?? [];
370
451
  if (extras.length > MAX_EXTRA_PERMISSIONS) {
371
452
  fail(m.id, `more than ${MAX_EXTRA_PERMISSIONS} extra permissions`);
@@ -392,6 +473,11 @@ export function validateManifest(m: FeatureManifest): void {
392
473
  }
393
474
  }
394
475
 
476
+ if (m.domains) {
477
+ if (!m.domains.hint.trim()) fail(m.id, 'domains: empty hint');
478
+ if (!m.domains.service.trim()) fail(m.id, 'domains: empty service');
479
+ }
480
+
395
481
  for (const scope of ['feature', 'item'] as const) {
396
482
  for (const tab of m.settings?.[scope] ?? []) {
397
483
  if (typeof tab === 'string') {
@@ -402,9 +488,16 @@ export function validateManifest(m: FeatureManifest): void {
402
488
  if (tab === 'sources' && scope === 'item') {
403
489
  fail(m.id, 'sources is a feature-scope tab');
404
490
  }
491
+ if (tab === 'domains' && !m.domains) fail(m.id, 'domains tab requires domains');
492
+ if (tab === 'domains' && scope === 'item') {
493
+ fail(m.id, 'domains is a feature-scope tab');
494
+ }
405
495
  if (tab === 'encryption' && scope === 'feature') {
406
496
  fail(m.id, 'encryption is an item-scope tab');
407
497
  }
498
+ if (!DECLARABLE_TABS.includes(tab)) {
499
+ fail(m.id, `unknown settings tab « ${String(tab)} »`);
500
+ }
408
501
  } else {
409
502
  if (!CUSTOM_TAB_PATTERN.test(tab.id) || BUILTIN_TABS.includes(tab.id)) {
410
503
  fail(m.id, `invalid custom tab id « ${tab.id} »`);
@@ -94,6 +94,39 @@ export interface DatabaseBackupProvider {
94
94
  * feature links to: same shape and reason as `UPTIME_ITEMS_PROVIDER`
95
95
  * (`project_database_links` is Projects' table).
96
96
  */
97
+ /**
98
+ * Key of the read-only measurement the Projects module consumes for its custom
99
+ * dashboard KPIs: the query goes through the SAME access as the monitoring (SSH
100
+ * tunnel or SOCKS proxy included), and only the Databases feature knows how to
101
+ * decrypt a connection.
102
+ */
103
+ export const DATABASE_MEASURE_PROVIDER = 'database.measure' as const;
104
+
105
+ /** One measured number, or the reason there is none. */
106
+ export interface DatabaseNumberOutcome {
107
+ value: number | null;
108
+ error: string | null;
109
+ }
110
+
111
+ export interface DatabaseMeasureProvider {
112
+ /**
113
+ * Measures read-only queries against a database visible from this
114
+ * workspace, in ONE session (tunnel included) whatever the number of
115
+ * queries: opening one per query would cost far more than the figures are
116
+ * worth.
117
+ *
118
+ * Each query must be a single read statement returning exactly one row and
119
+ * one column; one that is refused or faulty yields its error and does not
120
+ * interrupt the others, the way an alert's conditions behave. Answers
121
+ * `null`, never throws, when the database is not visible from there.
122
+ */
123
+ measure(
124
+ databaseId: number,
125
+ workspaceId: number,
126
+ queries: readonly string[]
127
+ ): Promise<readonly DatabaseNumberOutcome[] | null>;
128
+ }
129
+
97
130
  export const DATABASE_ITEMS_PROVIDER = 'database.items' as const;
98
131
 
99
132
  export interface DatabaseItemsProvider {
@@ -125,20 +158,40 @@ export interface MailSender {
125
158
  address: string;
126
159
  }
127
160
 
161
+ /**
162
+ * A file carried along a message: the `.ics` invitation of a booking, a small
163
+ * report. `Uint8Array` rather than `Buffer`: the published package does not
164
+ * depend on Node's types beyond `node:net`, and the adapter bridges it.
165
+ */
166
+ export interface MailAttachment {
167
+ filename: string;
168
+ contentType: string;
169
+ content: Uint8Array;
170
+ }
171
+
128
172
  export interface MailTransportProvider {
129
173
  /** The workspace's ready senders (open tier, enabled). */
130
174
  listSenders(workspaceId: number): Promise<readonly MailSender[]>;
131
175
  /** Is this account a ready sender of this workspace right now? */
132
176
  isReady(accountId: number, workspaceId: number): Promise<boolean>;
133
177
  /**
134
- * Sends one plain-text message from this account. Resolves `true` when the
135
- * provider accepted it; `false` (never a throw) when the account is not a
136
- * ready sender or the send failed, the failure logged by the module.
178
+ * Sends one message from this account. Resolves `true` when the provider
179
+ * accepted it; `false` (never a throw) when the account is not a ready
180
+ * sender or the send failed, the failure logged by the module.
181
+ *
182
+ * `text` stays mandatory whatever else is given: a recipient whose client
183
+ * shows no HTML must lose nothing.
137
184
  */
138
185
  send(
139
186
  accountId: number,
140
187
  workspaceId: number,
141
- message: { to: string; subject: string; text: string }
188
+ message: {
189
+ to: string;
190
+ subject: string;
191
+ text: string;
192
+ html?: string;
193
+ attachments?: readonly MailAttachment[];
194
+ }
142
195
  ): Promise<boolean>;
143
196
  }
144
197
 
@@ -264,6 +317,21 @@ export interface ProjectUsage {
264
317
  status: 'draft' | 'active' | 'paused' | 'done';
265
318
  }
266
319
 
320
+ /**
321
+ * A project an item of another feature can be attached to, in ONE workspace.
322
+ * Open tier and at home only: a guarded project links nothing, and a link is
323
+ * posed in the project's own workspace, never through a projection of it.
324
+ */
325
+ export interface ProjectLinkTarget {
326
+ projectId: number;
327
+ title: string;
328
+ status: 'draft' | 'active' | 'paused' | 'done';
329
+ /** Filed away: listed only while it still links the item, so the link can be undone. */
330
+ archived: boolean;
331
+ /** This project already links the item asked about. */
332
+ linked: boolean;
333
+ }
334
+
267
335
  export interface ProjectsUsageProvider {
268
336
  /** The workspace's projects linking this item of this feature, in Projects' display order. */
269
337
  usageOf(feature: string, itemId: number, workspaceId: number): Promise<readonly ProjectUsage[]>;
@@ -281,6 +349,40 @@ export interface ProjectsUsageProvider {
281
349
  * and zero for a feature that links nothing.
282
350
  */
283
351
  detach(feature: string, itemId: number, workspaceId: number): Promise<number>;
352
+ /**
353
+ * The projects of ONE workspace an item of this feature can be attached to,
354
+ * each saying whether it already links it. What the app's settings shell
355
+ * lists on an item, workspace by workspace.
356
+ *
357
+ * Only projects living in that workspace at the open tier: a link is posed
358
+ * at the project's home, and a guarded project links nothing. Filed-away
359
+ * projects appear only while they still hold a link, so a dead link can be
360
+ * undone without unfiling the project.
361
+ *
362
+ * Empty for a feature this provider links nothing of, so a caller never has
363
+ * to know which features are linkable.
364
+ */
365
+ linkTargets(
366
+ feature: string,
367
+ itemId: number,
368
+ workspaceId: number
369
+ ): Promise<readonly ProjectLinkTarget[]>;
370
+ /**
371
+ * Attaches the item to one project of this workspace. Idempotent: the same
372
+ * link declared twice is the same fact, not an error.
373
+ *
374
+ * The caller owns the authorisation (`projects: write` in that workspace)
375
+ * and has checked the item is visible from there; this only refuses what
376
+ * its own tables cannot hold, silently: an unknown or projected project,
377
+ * and a guarded one.
378
+ */
379
+ link(feature: string, itemId: number, workspaceId: number, projectId: number): Promise<void>;
380
+ /**
381
+ * Drops that one link, and never touches the item itself. Idempotent.
382
+ * Unlike {@link ProjectsUsageProvider.detach}, which drops every link of an
383
+ * item that left the workspace, this answers one screen's single switch.
384
+ */
385
+ unlink(feature: string, itemId: number, workspaceId: number, projectId: number): Promise<void>;
284
386
  /**
285
387
  * Writes one line in a project's timeline (a deployment triggered from a
286
388
  * project's tab). Open tier only: an event aimed at a guarded project is
@@ -373,3 +475,23 @@ export interface SentinelAgentConfigProvider {
373
475
  /** The device's contribution, or null when Sentinel knows nothing about it (probes off). */
374
476
  configFor(deviceId: string): Promise<SentinelAgentConfig | null>;
375
477
  }
478
+
479
+ /**
480
+ * The plan of an account: what bounds the quotas modules declare
481
+ * (`manifest.quotas`). Offered by a billing module. WITHOUT it every quota is
482
+ * unlimited, which is what a self-hosted DevEye is.
483
+ */
484
+ export const ACCOUNT_PLAN_PROVIDER = 'account.plan';
485
+
486
+ export interface AccountPlan {
487
+ id: string;
488
+ label: string;
489
+ /** `<featureId>.<quotaKey>` to its maximum. An absent key is unlimited. */
490
+ limits: Readonly<Record<string, number>>;
491
+ /** The plan is a trial ending then (ms since the epoch). */
492
+ trialEndsAt?: number;
493
+ }
494
+
495
+ export interface AccountPlanProvider {
496
+ planFor(userId: number): Promise<AccountPlan>;
497
+ }