@deveye/types 0.20.3 → 0.21.1

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/server.ts CHANGED
@@ -1,3 +1,5 @@
1
+ import type { Duplex } from 'node:stream';
2
+ import type { FeatureAccountExport } from './accountExport';
1
3
  import type { ItemTree, ItemTreeRows } from './copy';
2
4
  import type { z, ZodType } from 'zod';
3
5
  import type { ErrorCode } from '../protocol/error';
@@ -11,6 +13,7 @@ import type { AgentManifest } from '../http/device';
11
13
  import type { MetricSnapshot } from '../domain/metrics';
12
14
  import type { UserColor } from '../domain/user';
13
15
  import type { SdkDnsRecord } from './domains';
16
+ import type { MailTransportMessage } from './providers';
14
17
  import type { ModuleEnvSpec } from './env';
15
18
  import type {
16
19
  AgentSyncAckPayload,
@@ -26,6 +29,7 @@ import type {
26
29
  AgentSyncMovePayload,
27
30
  AgentSyncOpResultPayload,
28
31
  AgentSyncPushPayload,
32
+ AgentSyncPushAckPayload,
29
33
  AgentSyncScanPayload,
30
34
  AgentFilesMutatePayload,
31
35
  AgentFilesUploadPayload,
@@ -34,7 +38,15 @@ import type {
34
38
  CloudSyncStatePush
35
39
  } from '../protocol/agent';
36
40
 
37
- export { isPublicIp, isSafePublicUrl } from './net';
41
+ export {
42
+ isPublicIp,
43
+ isSafePublicUrl,
44
+ NetRefused,
45
+ resolvesPublicly,
46
+ safeFetchText,
47
+ type SafeFetchOptions
48
+ } from './net';
49
+ export { mapLimit } from './pool';
38
50
  export {
39
51
  defineModuleEnv,
40
52
  MODULE_ENV_NAME_PATTERN,
@@ -302,6 +314,21 @@ export interface DevEyeFacade {
302
314
  /** The CALLER's own account, never someone else's. */
303
315
  me(): Promise<SdkAccount>;
304
316
  };
317
+ /** Requires capability `'accounts.usage'`. */
318
+ usage: {
319
+ /**
320
+ * What this account uses of every limit this DevEye knows. The caller
321
+ * must be this account or a global administrator (`forbidden`
322
+ * otherwise); an unknown account throws `not_found`.
323
+ */
324
+ of(userId: number): Promise<SdkAccountUsage>;
325
+ /**
326
+ * `of` for many accounts, in the order given, unknown ids left out. A
327
+ * global administrator's surface only. The host paces the counting so a
328
+ * sweep never starves the database: one call, never one per account.
329
+ */
330
+ ofMany(userIds: readonly number[]): Promise<readonly SdkAccountUsage[]>;
331
+ };
305
332
  }
306
333
 
307
334
  /** An account of this DevEye, as `'accounts.read'` shows it. */
@@ -311,6 +338,14 @@ export interface SdkAccount {
311
338
  username: string;
312
339
  /** A global administrator of this DevEye. */
313
340
  isAdmin: boolean;
341
+ /**
342
+ * A throwaway account the app's end-to-end runner created and will delete:
343
+ * never a person, and its address receives nothing. Check this, never the
344
+ * address: it is set once, at creation, and nothing can grant it later.
345
+ */
346
+ e2e: boolean;
347
+ /** Suspended by an administrator: it keeps everything and cannot sign in. */
348
+ suspended: boolean;
314
349
  /** Milliseconds since the epoch. */
315
350
  created: number;
316
351
  }
@@ -327,6 +362,79 @@ export interface SdkAccounts {
327
362
  * and is capped at 50.
328
363
  */
329
364
  search(query: string, limit?: number): Promise<readonly SdkAccount[]>;
365
+ /** Every account, oldest first: an administrator's sweep. What you show of it is yours to gate. */
366
+ all(): Promise<readonly SdkAccount[]>;
367
+ }
368
+
369
+ /** What one account uses of one limit, whatever its plan allows. */
370
+ export interface SdkAccountQuotaUse {
371
+ /**
372
+ * `stock`: things that exist, the excess paused; `flow`: checked at each
373
+ * use, nothing paused; `perOperation`: one operation bounded, nothing counted.
374
+ */
375
+ kind: 'stock' | 'flow' | 'perOperation';
376
+ /**
377
+ * What the limit is compared to now, over every workspace the account
378
+ * OWNS: the things that exist, paused ones included, for a `stock`; this
379
+ * month's flow or the bytes held otherwise; for `workspace.members`, its
380
+ * fullest shared workspace. `null` for a `perOperation` limit.
381
+ */
382
+ used: number | null;
383
+ /** How many of them its plan holds paused, in the unit of `used`. 0 for anything but a stock. */
384
+ paused: number;
385
+ }
386
+
387
+ /** What one account uses, as `'accounts.usage'` reads it. */
388
+ export interface SdkAccountUsage {
389
+ userId: number;
390
+ /**
391
+ * By `<featureId>.<quotaKey>`: every quota of the installed modules and the
392
+ * host's own (`workspace.shared`, `workspace.members`, `domains.hosts`),
393
+ * bounded or not. The limits are the plan provider's (`planFor`).
394
+ */
395
+ quotas: Readonly<Record<string, SdkAccountQuotaUse>>;
396
+ }
397
+
398
+ /**
399
+ * Any account's usage, sessionless (capability `'accounts.usage'`), for
400
+ * services: the same reading as `ctx.deveye.usage`, without its caller check.
401
+ */
402
+ export interface SdkUsage {
403
+ of(userId: number): Promise<SdkAccountUsage>;
404
+ ofMany(userIds: readonly number[]): Promise<readonly SdkAccountUsage[]>;
405
+ }
406
+
407
+ /** One email to an account. Plain text everywhere: the host lays it out and escapes it. */
408
+ export interface SdkAccountMailMessage {
409
+ subject: string;
410
+ /** One paragraph each, in order. */
411
+ paragraphs: readonly string[];
412
+ /** Framed and set apart after the paragraphs: what the reader must not miss (a deadline). */
413
+ notice?: string;
414
+ /** A link drawn as a button, after the notice. */
415
+ button?: { label: string; url: string };
416
+ /** Small print, last. */
417
+ footnote?: string;
418
+ }
419
+
420
+ /** Emails to the accounts of this DevEye, from the server's own sender (capability `'accounts.mail'`). */
421
+ export interface SdkAccountMail {
422
+ /** `false` when this server has no mail transport: `send` would throw `conflict`. */
423
+ readonly configured: boolean;
424
+ /**
425
+ * Sends to the account's own address, never another, and resolves that
426
+ * address for your records. Throws `not_found` for an unknown account and
427
+ * `conflict` without a transport; a refusal of the mail server rejects as
428
+ * is. Nothing is retried for you.
429
+ */
430
+ send(userId: number, message: SdkAccountMailMessage): Promise<string>;
431
+ /**
432
+ * One copy to each active administrator of this DevEye, for what only the
433
+ * operator can act on (a report of illicit content). Resolves the addresses
434
+ * reached, empty when there is no active administrator. Every address is
435
+ * tried; the first refusal then rejects. Throws `conflict` without a transport.
436
+ */
437
+ sendToAdmins(message: SdkAccountMailMessage): Promise<readonly string[]>;
330
438
  }
331
439
 
332
440
  /**
@@ -348,6 +456,13 @@ export interface SdkPlanPauses {
348
456
  paused(key: string): readonly string[];
349
457
  }
350
458
 
459
+ /** Where the owner stands against one limit of YOUR `manifest.quotas`. */
460
+ export interface SdkQuotaUse {
461
+ /** By YOUR `server.quotas[key]`, over every workspace the owner owns. */
462
+ used: number;
463
+ limit: number;
464
+ }
465
+
351
466
  /**
352
467
  * What the account's plan allows of YOUR `manifest.quotas`. The account is the
353
468
  * OWNER of the workspace of the call: in a shared workspace, what a member
@@ -355,24 +470,41 @@ export interface SdkPlanPauses {
355
470
  * everything is unlimited.
356
471
  */
357
472
  export interface SdkQuota extends SdkPlanPauses {
358
- /** `null` = unlimited. An undeclared key throws `validation`. */
473
+ /**
474
+ * `null` = unlimited. An undeclared key throws `validation`. Reads 0 while
475
+ * the host serves priority accounts first and the owner is not one.
476
+ */
359
477
  limit(key: string): Promise<number | null>;
360
478
  /**
361
479
  * Call it BEFORE creating. `countAfter` receives the ids of every workspace
362
480
  * the owner account owns and returns how many there would be once created;
363
481
  * it is never called when unlimited. Throws `quota_exceeded` beyond the
364
- * limit.
482
+ * limit. Count with the same repo function as `server.quotas[key]`: the
483
+ * usage shown and the refusal must agree.
365
484
  */
366
485
  assert(
367
486
  key: string,
368
487
  countAfter: (ownerWorkspaceIds: readonly number[]) => Promise<number>
369
488
  ): Promise<void>;
489
+ /**
490
+ * Where the owner stands, counted by YOUR `server.quotas[key]`: what a
491
+ * screen says BEFORE the refusal. `null` = unlimited, and nothing is
492
+ * counted. A `perOperation` key throws `validation`: nothing accumulates.
493
+ */
494
+ usage(key: string): Promise<SdkQuotaUse | null>;
370
495
  /**
371
496
  * Call it before running a `stock` item on demand (check now, deploy now,
372
497
  * open a session): throws `quota_exceeded` when its owner's plan holds it
373
498
  * paused, which opens the plan prompt on the client.
374
499
  */
375
500
  assertActive(key: string, itemId: string): Promise<void>;
501
+ /**
502
+ * Whether the owner pays: a paid or trial plan, a plan granted on the paid
503
+ * tier, an administrator, or no plan provider at all (a self-hosted
504
+ * instance). What a default that costs the host keys on (a probe cadence),
505
+ * never a refusal: refusals go through `limit` and `assert`.
506
+ */
507
+ paid(): Promise<boolean>;
376
508
  }
377
509
 
378
510
  /** One item a `stock` quota counts. */
@@ -393,14 +525,24 @@ export interface SdkPlanPauseChange {
393
525
  resumed: readonly SdkStockItem[];
394
526
  }
395
527
 
396
- /** Your half of one `stock` quota: the host ranks, you list. */
397
- export interface FeatureStockEntry<Repo = unknown> {
528
+ /**
529
+ * How the host counts one of your quotas, for `ctx.quota.usage` and an
530
+ * account's usage (`'accounts.usage'`): a `stock` by its list, any other by
531
+ * its count, under the very WHERE of the counter you pass to `assert`.
532
+ */
533
+ export interface FeatureQuotaEntry<Repo = unknown> {
398
534
  /**
399
- * The items the quota counts in these workspaces, OLDEST FIRST (creation,
400
- * then id), under the very WHERE of the counter you pass to `assert`. The
535
+ * `stock` quotas only, required there: the items the quota counts in these
536
+ * workspaces, OLDEST FIRST (creation, then id). How many is the usage; the
401
537
  * host keeps the first `limit` running and pauses the rest.
402
538
  */
403
- list(repo: Repo, ownerWorkspaceIds: readonly number[]): Promise<readonly SdkStockItem[]>;
539
+ list?(repo: Repo, ownerWorkspaceIds: readonly number[]): Promise<readonly SdkStockItem[]>;
540
+ /**
541
+ * Any other quota but `perOperation`, required there: what the limit is
542
+ * compared to now (this month's events, the bytes held). A month is the
543
+ * current UTC month unless your feature keeps a calendar of its own.
544
+ */
545
+ count?(repo: Repo, ownerWorkspaceIds: readonly number[]): Promise<number>;
404
546
  }
405
547
 
406
548
  /** A workspace as the fleet sees it: enough to attach a device to it. */
@@ -447,9 +589,21 @@ export interface AgentsFacade {
447
589
  * offline (it receives the config at its next connection anyway).
448
590
  */
449
591
  pushConfig(deviceId: string): Promise<boolean>;
592
+ /**
593
+ * The cadence each device's agent runs at, by device id: its own setting,
594
+ * or the default of the plan of its HOME workspace's owner.
595
+ */
596
+ metricIntervals(
597
+ devices: readonly {
598
+ id: string;
599
+ workspace_id: number | null;
600
+ metric_interval_seconds: number | null;
601
+ }[]
602
+ ): Promise<ReadonlyMap<string, number>>;
450
603
  requestSyncConfig(deviceId: string, payload: AgentSyncConfigPayload): boolean;
451
604
  requestSyncScan(deviceId: string, payload: AgentSyncScanPayload): boolean;
452
605
  requestSyncPush(deviceId: string, payload: AgentSyncPushPayload): boolean;
606
+ requestSyncPushAck(deviceId: string, payload: AgentSyncPushAckPayload): boolean;
453
607
  requestSyncApplyChunk(deviceId: string, payload: AgentSyncApplyChunkPayload): boolean;
454
608
  requestSyncApplyStart(deviceId: string, payload: AgentSyncApplyStartPayload): boolean;
455
609
  requestSyncApplyDir(deviceId: string, payload: AgentSyncApplyDirPayload): boolean;
@@ -502,6 +656,19 @@ export interface AgentsFacade {
502
656
  request: AgentFolderArchiveRequest,
503
657
  options?: { signal?: AbortSignal }
504
658
  ): AgentFolderArchive;
659
+ /**
660
+ * A TCP connection opened BY THE DEVICE to `host:port` and relayed by its
661
+ * agent: a service only the machine can reach (a database on its
662
+ * loopback) becomes a stream here, read at the consumer's pace. The agent
663
+ * only reaches its own loopback, plus the hosts its operator lists in
664
+ * `tunnel_targets`, and refuses everything under `allow_tunnel = false`.
665
+ * Rejects with the reason (offline, refused, unreachable, an agent that
666
+ * predates the order: check `report.agent.probes` for
667
+ * `AGENT_TUNNEL_PROBE` first to say so plainly). Once open, the stream is
668
+ * destroyed with an error when the device goes offline; ending or
669
+ * destroying it closes the connection on the machine.
670
+ */
671
+ openTcp(deviceId: string, target: { host: string; port: number }): Promise<Duplex>;
505
672
  /**
506
673
  * Bytes queued on the agent's socket, not yet on the wire. A sender that
507
674
  * streams towards an agent must watch it: the socket accepts everything,
@@ -594,6 +761,58 @@ export interface SdkProviders {
594
761
  get<T>(key: string): T | undefined;
595
762
  }
596
763
 
764
+ /** One object of an {@link SdkObjectStore}, as `list` yields it. */
765
+ export interface SdkStoredObject {
766
+ key: string;
767
+ size: number;
768
+ }
769
+
770
+ /**
771
+ * Where a module keeps files (capability `'objects'`): the server's disk, or
772
+ * the S3 bucket the host configured. A key is a relative path (`a/b/c`, no
773
+ * `..`, no leading `/`); store only the KEY in your tables, never where it
774
+ * resolves, so the host can move the whole tree (another disk, another
775
+ * bucket) without a row to rewrite. Writes are atomic: a reader sees the
776
+ * whole object or none.
777
+ */
778
+ export interface SdkObjectStore {
779
+ /** `'local'`: the server's disk. `'s3'`: every byte read costs egress. */
780
+ readonly kind: 'local' | 's3';
781
+ /** Where it lives, for a screen: « disque du serveur », « S3 : bucket ». */
782
+ describe(): string;
783
+ put(key: string, body: AsyncIterable<Uint8Array> | Uint8Array): Promise<{ size: number }>;
784
+ /**
785
+ * Stores a finished local file under `key`, then removes the local file:
786
+ * a rename on the server's disk, an upload on S3. For a file assembled
787
+ * in {@link spoolDir}.
788
+ */
789
+ putFile(key: string, localPath: string): Promise<{ size: number }>;
790
+ /** The object's bytes, streamed. `range` is inclusive, like HTTP's. Throws when absent. */
791
+ get(key: string, range?: { start: number; end?: number }): AsyncIterable<Buffer>;
792
+ /** `null` when absent. */
793
+ head(key: string): Promise<{ size: number } | null>;
794
+ /** Every object whose key starts with `prefix`, in no guaranteed order. */
795
+ list(prefix: string): AsyncIterable<SdkStoredObject>;
796
+ /** Idempotent: an absent key is not an error. */
797
+ delete(key: string): Promise<void>;
798
+ /** Every object under `prefix`, which must end with `/`. */
799
+ deletePrefix(prefix: string): Promise<void>;
800
+ /**
801
+ * A directory on the server's disk, whatever `kind`, for what cannot be
802
+ * written as a whole object at once (a partial upload resumed later).
803
+ * Yours alone; the store never cleans it.
804
+ */
805
+ spoolDir(): string;
806
+ /**
807
+ * The store's root when files written there would not last: on the
808
+ * server's disk, inside a container, a directory on no mounted volume,
809
+ * so its writable layer, wiped at the next redeploy. `null` otherwise,
810
+ * and always on S3. Refuse to write there, naming the variable that sets
811
+ * `localDir`: the files would vanish without a word.
812
+ */
813
+ ephemeralRoot(): Promise<string | null>;
814
+ }
815
+
597
816
  /**
598
817
  * Raw bytes under the SERVER key, for wrapping module-owned key material; never
599
818
  * for user data, which goes through ciphers and the store. The host seals under
@@ -632,6 +851,8 @@ export interface SdkDevice {
632
851
  workspaceId: number | null;
633
852
  /** The agent's metric cadence in seconds, null when it follows the default. */
634
853
  metricIntervalSeconds: number | null;
854
+ /** The cadence the agent actually runs at: its own, or the default of its owner's plan. */
855
+ effectiveMetricIntervalSeconds: number;
635
856
  /** The last OS/security report, null before the first one (or unreadable). */
636
857
  report: DeviceReport | null;
637
858
  }
@@ -1159,8 +1380,33 @@ export interface FeatureService {
1159
1380
  * rows go with the account (`ON DELETE CASCADE`), nothing to do for them.
1160
1381
  * Runs before the row is deleted: a throw aborts the deletion. Never called
1161
1382
  * while your service is halted by maintenance: the deletion is refused then.
1383
+ * Return a note when the holder must learn something of yours (their
1384
+ * subscription stopped): it joins the confirmation email they receive.
1385
+ */
1386
+ onAccountDeleted?(
1387
+ userId: number
1388
+ ): void | SdkAccountDeletedNote | Promise<void | SdkAccountDeletedNote>;
1389
+ /**
1390
+ * What your service knows of its own health that the host cannot see: a
1391
+ * port it failed to open, an engine it depends on. Read by the public
1392
+ * status page about once a minute. Answer from memory: no network call, no
1393
+ * write, no heavy query; after 2 s the host counts you as degraded. Omit it
1394
+ * when the process and the database are all you rely on: the host already
1395
+ * watches those, along with your failing tickers and commands.
1162
1396
  */
1163
- onAccountDeleted?(userId: number): void | Promise<void>;
1397
+ health?(): SdkServiceHealth | Promise<SdkServiceHealth>;
1398
+ }
1399
+
1400
+ /** A service's own verdict on itself, as `FeatureService.health` gives it. */
1401
+ export interface SdkServiceHealth {
1402
+ state: 'up' | 'degraded' | 'down';
1403
+ /** Shown on the public status page: a short sentence for users, never an internal detail. */
1404
+ reason?: string;
1405
+ }
1406
+
1407
+ /** One paragraph of yours in the email confirming an account's deletion to its holder. */
1408
+ export interface SdkAccountDeletedNote {
1409
+ paragraph: string;
1164
1410
  }
1165
1411
 
1166
1412
  /**
@@ -1184,6 +1430,10 @@ export interface FeatureServiceDeps<Repo = unknown> {
1184
1430
  devices: SdkFleetDevices;
1185
1431
  /** Capability `'accounts.read'`. */
1186
1432
  accounts: SdkAccounts;
1433
+ /** Capability `'accounts.usage'`. */
1434
+ usage: SdkUsage;
1435
+ /** Capability `'accounts.mail'`. */
1436
+ accountMail: SdkAccountMail;
1187
1437
  /**
1188
1438
  * {@link SdkQuota} for a workspace, sessionless: for what gets created
1189
1439
  * outside any command (bytes an agent uploads). Same account rule, the
@@ -1234,6 +1484,12 @@ export interface FeatureServiceDeps<Repo = unknown> {
1234
1484
  };
1235
1485
  /** Raw key wrapping under the server key, and derived keys. */
1236
1486
  keys: SdkServerKeys;
1487
+ /**
1488
+ * The object store (capability `'objects'`). `localDir` is where your
1489
+ * objects live while the host keeps them on its disk, typically a path of
1490
+ * your `env`; with an S3 configured, it only holds your `spoolDir()`.
1491
+ */
1492
+ objects(localDir: string): SdkObjectStore;
1237
1493
  /** Redeems a ticket minted by `ctx.secrecy.ticket` of THIS module; `null` when invalid, expired or another module's. */
1238
1494
  secrecy: { redeem(ticket: string): Promise<SdkRedeemedTicket | null> };
1239
1495
  /** Where DevEye lives (the same `origins` a request context gets): for a page or a link a route hands to the browser. */
@@ -1275,14 +1531,131 @@ export interface FeatureServer<Repo = unknown> {
1275
1531
  items?: FeatureItemsEntry<Repo>;
1276
1532
  /** Required when the manifest declares `domains`, refused otherwise. */
1277
1533
  domains?: FeatureDomainsEntry<Repo>;
1278
- /** One entry per `stock` quota of the manifest, by its key, and none other. */
1279
- quotas?: Readonly<Record<string, FeatureStockEntry<Repo>>>;
1534
+ /**
1535
+ * What the holder's data export writes of your feature (GDPR
1536
+ * portability): see {@link FeatureAccountExport}. Required once your
1537
+ * feature owns a table; without tables, the host exports your store alone.
1538
+ */
1539
+ accountExport?: FeatureAccountExport<Repo>;
1540
+ /** One entry per quota of the manifest, by its key, `perOperation` ones excepted, and none other. */
1541
+ quotas?: Readonly<Record<string, FeatureQuotaEntry<Repo>>>;
1280
1542
  /**
1281
1543
  * The environment variables you read, as the spec you read them with
1282
1544
  * (`defineModuleEnv`). Plain data: the host reads it again at boot and
1283
1545
  * warns about every variable left to its default.
1284
1546
  */
1285
1547
  env?: ModuleEnvSpec;
1548
+ /**
1549
+ * Every email you send, on made-up data, for the administrator's mail
1550
+ * tester: built by the SAME function as the real one, or the tester proves
1551
+ * nothing. `sender: 'server'` requires capability `'accounts.mail'`. Keys
1552
+ * are unique within your feature.
1553
+ */
1554
+ mailSamples?: readonly SdkMailSample[];
1555
+ /** Your end-to-end scenarios, run by an administrator against this very server. */
1556
+ e2e?: FeatureE2eEntry<Repo>;
1557
+ }
1558
+
1559
+ /** What a mail sample is built with. */
1560
+ export interface SdkMailSampleContext {
1561
+ origins: SdkOrigins;
1562
+ /** Milliseconds since the epoch. */
1563
+ now: number;
1564
+ }
1565
+
1566
+ /** A message a workspace mailbox sends: what `MailTransportProvider.send` takes, the recipient aside. */
1567
+ export type SdkWorkspaceMail = Omit<MailTransportMessage, 'to'>;
1568
+
1569
+ export type SdkMailSample = {
1570
+ /** `[a-z][a-zA-Z0-9]*`, unique within your feature. */
1571
+ key: string;
1572
+ /** What the tester lists, in the interface's language. */
1573
+ label: string;
1574
+ } & (
1575
+ | {
1576
+ /** From the server's own sender, as `accountMail.send` would. */
1577
+ sender: 'server';
1578
+ build(ctx: SdkMailSampleContext): SdkAccountMailMessage | Promise<SdkAccountMailMessage>;
1579
+ }
1580
+ | {
1581
+ /** From a workspace mailbox the administrator picks, as `MAIL_TRANSPORT_PROVIDER` would. */
1582
+ sender: 'workspace';
1583
+ build(ctx: SdkMailSampleContext): SdkWorkspaceMail | Promise<SdkWorkspaceMail>;
1584
+ }
1585
+ );
1586
+
1587
+ /** The throwaway account a scenario runs as. It owns `workspaceId` and is deleted with all it owns afterwards. */
1588
+ export interface SdkE2eAccount {
1589
+ userId: number;
1590
+ username: string;
1591
+ email: string;
1592
+ password: string;
1593
+ /** Its personal workspace. */
1594
+ workspaceId: number;
1595
+ }
1596
+
1597
+ export interface SdkE2eContext<Repo = unknown> {
1598
+ account: SdkE2eAccount;
1599
+ /**
1600
+ * A command through a real socket of that account and the whole
1601
+ * dispatcher. Rejects with a `FeatureError` carrying the server's code.
1602
+ */
1603
+ send<T = unknown>(command: string, input: unknown, opts?: { workspaceId?: number }): Promise<T>;
1604
+ /** A sessionless request to this server's own listener: what a visitor's browser sends to a public route. */
1605
+ fetch(
1606
+ path: string,
1607
+ init?: { method?: 'GET' | 'POST'; headers?: Record<string, string>; body?: string }
1608
+ ): Promise<{ status: number; body: string }>;
1609
+ /**
1610
+ * Polls until `probe` answers something other than `null`, `undefined` or
1611
+ * `false`, then resolves with it. Rejects after `timeoutMs` (default 10 s),
1612
+ * saying `what` was awaited.
1613
+ */
1614
+ waitFor<T>(
1615
+ probe: () => Promise<T | null | undefined | false>,
1616
+ opts?: { timeoutMs?: number; intervalMs?: number; what?: string }
1617
+ ): Promise<T>;
1618
+ /**
1619
+ * Undoes something once the steps are over, whatever happened, last
1620
+ * registered first, while the account still exists. Register the undo
1621
+ * right after the thing is created, before anything can fail.
1622
+ */
1623
+ defer(label: string, undo: () => Promise<void>): void;
1624
+ /** Shared between the steps of one run. */
1625
+ state: Map<string, unknown>;
1626
+ repo: Repo;
1627
+ origins: SdkOrigins;
1628
+ /** Aborted when the administrator stops the run or a timeout fires. */
1629
+ signal: AbortSignal;
1630
+ }
1631
+
1632
+ export interface SdkE2eStep<Repo = unknown> {
1633
+ /** What the report shows, in the interface's language. */
1634
+ label: string;
1635
+ /** Longer than the default 20 s: a step that waits on a third party (a payment provider's webhook). */
1636
+ timeoutMs?: number;
1637
+ /** Throws to fail. A returned string is shown as the step's detail. */
1638
+ run(ctx: SdkE2eContext<Repo>): Promise<string | void>;
1639
+ }
1640
+
1641
+ export interface SdkE2eScenario<Repo = unknown> {
1642
+ /** `[a-z][a-zA-Z0-9]*`, unique within your feature. */
1643
+ id: string;
1644
+ label: string;
1645
+ /** Why it cannot run here right now, or `null`. Asked before every run. */
1646
+ skip?(ctx: { origins: SdkOrigins }): string | null | Promise<string | null>;
1647
+ steps: readonly SdkE2eStep<Repo>[];
1648
+ }
1649
+
1650
+ export interface FeatureE2eEntry<Repo = unknown> {
1651
+ scenarios: readonly SdkE2eScenario<Repo>[];
1652
+ /**
1653
+ * Removes what a crashed run left OUTSIDE the test accounts (an object at
1654
+ * a payment provider): what lives in your tables goes with the account.
1655
+ * Called at boot, before and after every run. Idempotent; a throw keeps
1656
+ * the run marked as leaving residue.
1657
+ */
1658
+ sweep?(): Promise<void>;
1286
1659
  }
1287
1660
 
1288
1661
  /**
@@ -1610,7 +1983,18 @@ export type {
1610
1983
  ItemTreeTable
1611
1984
  } from './copy';
1612
1985
 
1613
- // Le conteneur chiffré que CloudSync et Backup partagent (voir `devb.ts`).
1986
+ export { accountExportProblem, EXPORT_SECRET_COLUMN, exportTableRows } from './accountExport';
1987
+ export type {
1988
+ FeatureAccountExport,
1989
+ SdkAccountExportContext,
1990
+ SdkExportFiles,
1991
+ SdkExportSkip,
1992
+ SdkExportTable,
1993
+ SdkExportWriter,
1994
+ SdkWorkspaceExportContext
1995
+ } from './accountExport';
1996
+
1997
+ // Le conteneur chiffré des modules qui stockent des fichiers (voir `devb.ts`).
1614
1998
  export {
1615
1999
  BLOB_CHUNK_BYTES,
1616
2000
  BLOB_CHUNK_SEALED,
@@ -1620,7 +2004,12 @@ export {
1620
2004
  BLOB_VERSION_STREAM,
1621
2005
  createBlobHeader,
1622
2006
  openChunk,
2007
+ openSealedRange,
2008
+ openSealedStream,
1623
2009
  openStreamDecipher,
1624
2010
  parseBlobHeader,
1625
- sealChunk
2011
+ sealChunk,
2012
+ sealedSize,
2013
+ sealStream
1626
2014
  } from './devb';
2015
+ export { contentDisposition, parseByteRange } from './download';
@@ -80,6 +80,8 @@ test('the harness searches accounts like the app: substring, exact id first, cap
80
80
  username,
81
81
  email: `${username}@example.com`,
82
82
  isAdmin: false,
83
+ e2e: false,
84
+ suspended: false,
83
85
  created: 0
84
86
  });
85
87
  const { accounts } = createTestServiceDeps({
@@ -94,6 +96,10 @@ test('the harness searches accounts like the app: substring, exact id first, cap
94
96
  assert.deepEqual(await ids('12abc'), []);
95
97
  assert.deepEqual(await ids('', 1), [12]);
96
98
  assert.equal((await ids('', 0)).length, 1, 'a limit below one is raised to one');
99
+ assert.deepEqual(
100
+ (await accounts.all()).map((a) => a.id),
101
+ [7, 12, 3]
102
+ );
97
103
  });
98
104
 
99
105
  test('the harness scopes domains to the workspace, and finds a host whatever its spelling', async () => {
@@ -144,6 +150,66 @@ test('the harness bounds a quota like the app: never counted when unlimited, ref
144
150
  assert.deepEqual(bounded.recorded.accountChanges, [7]);
145
151
  });
146
152
 
153
+ test('the harness reads usage like the app: nothing counted when unlimited, a stock by its list', async () => {
154
+ let counted = 0;
155
+ const quotas = {
156
+ monitors: {
157
+ list: (_repo: undefined, owned: readonly number[]) => {
158
+ counted++;
159
+ return Promise.resolve(owned.map((id) => ({ id: String(id), workspaceId: id })));
160
+ }
161
+ },
162
+ events: {
163
+ count: (_repo: undefined, owned: readonly number[]) => {
164
+ counted++;
165
+ return Promise.resolve(owned.length * 10);
166
+ }
167
+ }
168
+ };
169
+ assert.equal(await createTestContext({ quotas }).quota.usage('monitors'), null);
170
+ assert.equal(counted, 0);
171
+
172
+ const ctx = createTestContext({
173
+ quotas,
174
+ quotaLimits: { monitors: 0, events: 50 },
175
+ ownerWorkspaceIds: [1, 2]
176
+ });
177
+ assert.deepEqual(await ctx.quota.usage('monitors'), { used: 2, limit: 0 });
178
+ assert.deepEqual(await ctx.quota.usage('events'), { used: 20, limit: 50 });
179
+ assert.deepEqual(
180
+ await createTestServiceDeps({ quotas, quotaLimits: { events: 5 } })
181
+ .quotaFor(1)
182
+ .usage('events'),
183
+ { used: 10, limit: 5 }
184
+ );
185
+ await assert.rejects(
186
+ createTestContext({ quotaLimits: { monitors: 1 } }).quota.usage('monitors'),
187
+ /pass your server's quotas/
188
+ );
189
+ });
190
+
191
+ test('the harness reads an account usage like the app: its own, or anyone for an administrator', async () => {
192
+ const accountUsage = [
193
+ { userId: 1, quotas: { 'x.monitors': { kind: 'stock' as const, used: 2, paused: 0 } } },
194
+ { userId: 2, quotas: { 'x.monitors': { kind: 'stock' as const, used: 9, paused: 4 } } }
195
+ ];
196
+ const me = createTestContext({ userId: 1, accountUsage });
197
+ assert.equal((await me.deveye.usage.of(1)).quotas['x.monitors'].used, 2);
198
+ await assert.rejects(me.deveye.usage.of(2), { code: 'forbidden' });
199
+ await assert.rejects(me.deveye.usage.ofMany([1]), { code: 'forbidden' });
200
+
201
+ const admin = createTestContext({ userId: 1, isAdmin: true, accountUsage });
202
+ assert.deepEqual(
203
+ (await admin.deveye.usage.ofMany([2, 5, 1])).map((u) => u.userId),
204
+ [2, 1]
205
+ );
206
+ await assert.rejects(admin.deveye.usage.of(5), { code: 'not_found' });
207
+ assert.equal(
208
+ (await createTestServiceDeps({ accountUsage }).usage.of(2)).quotas['x.monitors'].paused,
209
+ 4
210
+ );
211
+ });
212
+
147
213
  test('the harnesses hold the plan pauses and refuse a paused item on demand', async () => {
148
214
  const ctx = createTestContext({ pausedItems: { monitors: ['7'] } });
149
215
  assert.equal(ctx.quota.isPaused('monitors', '7'), true);