@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/package.json +1 -1
- package/src/domain/device.ts +6 -2
- package/src/domain/featureDomain.ts +46 -0
- package/src/domain/featureRegistry.ts +28 -0
- package/src/domain/home.ts +7 -4
- package/src/domain/live.ts +15 -5
- package/src/domain/project.ts +56 -0
- package/src/domain/report.ts +34 -2
- package/src/domain/secrecy.ts +3 -0
- package/src/domain/twoFactor.ts +7 -3
- package/src/domain/workspace.ts +1 -1
- package/src/domain/workspaceRole.ts +9 -2
- package/src/features/admin.ts +1 -51
- package/src/features/domain.ts +40 -0
- package/src/features/home.ts +1 -1
- package/src/features/links.ts +37 -0
- package/src/features/registry.ts +4 -0
- package/src/features/secrecy.ts +22 -8
- package/src/features/twoFactor.ts +1 -1
- package/src/features/user.ts +32 -4
- package/src/features/workspace.ts +2 -2
- package/src/http/auth.ts +64 -11
- package/src/http/device.ts +14 -10
- package/src/index.ts +65 -10
- package/src/protocol/agent.ts +38 -0
- package/src/protocol/error.ts +3 -0
- package/src/sdk/client-ambient.d.ts +60 -1
- package/src/sdk/client.ts +103 -5
- package/src/sdk/domains.test.ts +30 -0
- package/src/sdk/domains.ts +29 -0
- package/src/sdk/manifest.test.ts +60 -0
- package/src/sdk/manifest.ts +97 -4
- package/src/sdk/providers.ts +126 -4
- package/src/sdk/server.ts +198 -10
- package/src/sdk/testing.test.ts +55 -1
- package/src/sdk/testing.ts +192 -2
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
|
|
55
|
-
/** The full view, opened when the card expands. */
|
|
56
|
-
Full
|
|
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<{
|
|
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
|
+
}
|
package/src/sdk/manifest.test.ts
CHANGED
|
@@ -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
|
+
});
|
package/src/sdk/manifest.ts
CHANGED
|
@@ -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 `'
|
|
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} »`);
|
package/src/sdk/providers.ts
CHANGED
|
@@ -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
|
|
135
|
-
*
|
|
136
|
-
*
|
|
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: {
|
|
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
|
+
}
|