@lavitre/apps 1.53.0 → 1.56.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.
Files changed (39) hide show
  1. package/README.md +180 -0
  2. package/dist/Common/AppSettings.d.ts +34 -0
  3. package/dist/Common/AppSettings.js +35 -0
  4. package/dist/Common/AppSettings.js.map +1 -0
  5. package/dist/Common/Common.Model.d.ts +271 -0
  6. package/dist/Common/Common.Model.js.map +1 -1
  7. package/dist/Common/PrivateStorage.d.ts +249 -0
  8. package/dist/Common/PrivateStorage.js +158 -0
  9. package/dist/Common/PrivateStorage.js.map +1 -0
  10. package/dist/Common/PublicStorage.d.ts +140 -0
  11. package/dist/Common/PublicStorage.js +88 -0
  12. package/dist/Common/PublicStorage.js.map +1 -0
  13. package/dist/Common/index.d.ts +3 -0
  14. package/dist/Common/index.js +3 -0
  15. package/dist/Common/index.js.map +1 -1
  16. package/dist/CompanionConnector/CompanionConnector.Model.d.ts +11 -3
  17. package/dist/CompanionConnector/CompanionConnector.Model.js.map +1 -1
  18. package/dist/CompanionConnector/CompanionConnector.d.ts +14 -0
  19. package/dist/CompanionConnector/CompanionConnector.js +122 -0
  20. package/dist/CompanionConnector/CompanionConnector.js.map +1 -1
  21. package/dist/CompanionFrame/CompanionFrame.d.ts +13 -2
  22. package/dist/CompanionFrame/CompanionFrame.js.map +1 -1
  23. package/dist/Connector/Connector.Model.d.ts +29 -1
  24. package/dist/Connector/Connector.Model.js.map +1 -1
  25. package/dist/Connector/Connector.d.ts +60 -1
  26. package/dist/Connector/Connector.js +280 -1
  27. package/dist/Connector/Connector.js.map +1 -1
  28. package/dist/Frame/Frame.Model.d.ts +36 -2
  29. package/dist/Frame/Frame.Model.js.map +1 -1
  30. package/dist/Frame/Frame.d.ts +68 -3
  31. package/dist/Frame/Frame.js +326 -3
  32. package/dist/Frame/Frame.js.map +1 -1
  33. package/dist/Frame/SharedStreamPeer.d.ts +16 -0
  34. package/dist/Frame/SharedStreamPeer.js +74 -0
  35. package/dist/Frame/SharedStreamPeer.js.map +1 -0
  36. package/dist/Version.d.ts +1 -1
  37. package/dist/Version.js +1 -1
  38. package/dist/Version.js.map +1 -1
  39. package/package.json +1 -1
@@ -3,6 +3,9 @@ import { randomUuid } from '../Common/Uuid.js';
3
3
  import { CrdtChannel, MIN_CRDT_HOST_VERSION } from '../Common/CrdtChannel.js';
4
4
  import { BlobStore } from '../Common/BlobStore.js';
5
5
  import { isMinVersion } from '../Common/index.js';
6
+ import { AppSettingsError, APP_SETTINGS_TIMEOUT_MS } from '../Common/AppSettings.js';
7
+ import { PublicStorageError, PUBLIC_STORAGE_TIMEOUT_MS, PUBLIC_STORAGE_PUT_TIMEOUT_MS, MAX_PUBLIC_FILE_SIZE_BYTES, validateExpiresIn, putPublicFileExpiryField, withDownloadUrlFallback, } from '../Common/PublicStorage.js';
8
+ import { PrivateStorageError, PRIVATE_STORAGE_TIMEOUT_MS, PRIVATE_STORAGE_PUT_TIMEOUT_MS, PRIVATE_STORAGE_GET_TIMEOUT_MS, MAX_PRIVATE_FILE_SIZE_BYTES, validatePrivatePath, validatePrivateExpiresIn, validateLinkExpiresIn, privateFileExpiryField, } from '../Common/PrivateStorage.js';
6
9
  import { apiVersion } from '../Version.js';
7
10
  import { normalizeSettingsSchema } from './SettingsSchema.js';
8
11
  export class Connector {
@@ -145,6 +148,18 @@ export class Connector {
145
148
  writable: true,
146
149
  value: void 0
147
150
  });
151
+ /**
152
+ * Pushed whenever the AppSettings value at a given level changes — see
153
+ * {@link getSettings} / {@link setSettings}. Fires for changes made by
154
+ * this app itself as well as by another vitre/app instance sharing the
155
+ * same team/space. Added 1.52.
156
+ */
157
+ Object.defineProperty(this, "onSettingsChanged", {
158
+ enumerable: true,
159
+ configurable: true,
160
+ writable: true,
161
+ value: void 0
162
+ });
148
163
  Object.defineProperty(this, "onVitreSettingsUpdated", {
149
164
  enumerable: true,
150
165
  configurable: true,
@@ -379,6 +394,165 @@ export class Connector {
379
394
  writable: true,
380
395
  value: void 0
381
396
  });
397
+ /**
398
+ * Public, unauthenticated file storage scoped to the vitre's TEAM — see
399
+ * the README "Public storage" section for the full semantics (scopes,
400
+ * allowed file types, size cap, path rules). Files are readable by
401
+ * ANYONE at the returned URL — never put private data here.
402
+ */
403
+ Object.defineProperty(this, "publicStorage", {
404
+ enumerable: true,
405
+ configurable: true,
406
+ writable: true,
407
+ value: {
408
+ put: async (path, data, contentType, scope = 'app', options) => {
409
+ validateExpiresIn(options?.expiresIn);
410
+ const buffer = await this.toPublicFileBuffer(data);
411
+ if (buffer.byteLength > MAX_PUBLIC_FILE_SIZE_BYTES) {
412
+ throw new PublicStorageError('tooLarge');
413
+ }
414
+ const requestId = randomUuid();
415
+ return await this.postRequest({
416
+ type: 'putPublicFile',
417
+ requestId,
418
+ scope,
419
+ path,
420
+ contentType,
421
+ data: buffer,
422
+ ...putPublicFileExpiryField(options?.expiresIn),
423
+ }, (msg, resolve, reject) => {
424
+ if (msg.type === 'publicStorageResponse' && msg.requestId === requestId) {
425
+ if (msg.ok) {
426
+ resolve(withDownloadUrlFallback(msg.file ?? { path, url: msg.url ?? '', size: buffer.byteLength }));
427
+ }
428
+ else {
429
+ reject(new PublicStorageError(msg.error ?? 'failed'));
430
+ }
431
+ }
432
+ }, [buffer], { ms: PUBLIC_STORAGE_PUT_TIMEOUT_MS, onTimeout: () => new PublicStorageError('unsupported') });
433
+ },
434
+ delete: async (path, scope = 'app') => {
435
+ const requestId = randomUuid();
436
+ await this.postRequest({ type: 'deletePublicFile', requestId, scope, path }, (msg, resolve, reject) => {
437
+ if (msg.type === 'publicStorageResponse' && msg.requestId === requestId) {
438
+ if (msg.ok)
439
+ resolve(undefined);
440
+ else
441
+ reject(new PublicStorageError(msg.error ?? 'failed'));
442
+ }
443
+ }, undefined, { ms: PUBLIC_STORAGE_TIMEOUT_MS, onTimeout: () => new PublicStorageError('unsupported') });
444
+ },
445
+ list: async (prefix, scope = 'app') => {
446
+ const requestId = randomUuid();
447
+ return await this.postRequest({ type: 'listPublicFiles', requestId, scope, prefix }, (msg, resolve, reject) => {
448
+ if (msg.type === 'publicStorageResponse' && msg.requestId === requestId) {
449
+ if (msg.ok) {
450
+ resolve({
451
+ baseUrl: msg.baseUrl ?? '',
452
+ files: (msg.files ?? []).map(withDownloadUrlFallback),
453
+ });
454
+ }
455
+ else
456
+ reject(new PublicStorageError(msg.error ?? 'failed'));
457
+ }
458
+ }, undefined, { ms: PUBLIC_STORAGE_TIMEOUT_MS, onTimeout: () => new PublicStorageError('unsupported') });
459
+ },
460
+ }
461
+ });
462
+ /**
463
+ * Private file storage scoped to the vitre's TEAM — see the README
464
+ * "Private storage" section for the full semantics. Unlike
465
+ * `publicStorage`, files here have no public link: readable by any
466
+ * vitre or companion of the team via `get` or a temporary `getLink`
467
+ * signed link, never by an anonymous visitor. Write-only on a
468
+ * Vitre-hosted app — `CompanionConnector` only has `list`/`get`/`getLink`.
469
+ */
470
+ Object.defineProperty(this, "privateStorage", {
471
+ enumerable: true,
472
+ configurable: true,
473
+ writable: true,
474
+ value: {
475
+ put: async (path, data, contentType, scope = 'app', options) => {
476
+ validatePrivatePath(path);
477
+ validatePrivateExpiresIn(options?.expiresIn);
478
+ const buffer = await this.toPrivateFileBuffer(data);
479
+ if (buffer.byteLength > MAX_PRIVATE_FILE_SIZE_BYTES) {
480
+ throw new PrivateStorageError('tooLarge');
481
+ }
482
+ const requestId = randomUuid();
483
+ return await this.postRequest({
484
+ type: 'putPrivateFile',
485
+ requestId,
486
+ scope,
487
+ path,
488
+ contentType,
489
+ data: buffer,
490
+ ...privateFileExpiryField(options?.expiresIn),
491
+ }, (msg, resolve, reject) => {
492
+ if (msg.type === 'privateStorageResponse' && msg.requestId === requestId) {
493
+ if (msg.ok) {
494
+ resolve(msg.file ?? { path, size: buffer.byteLength, contentType });
495
+ }
496
+ else {
497
+ reject(new PrivateStorageError(msg.error ?? 'failed'));
498
+ }
499
+ }
500
+ }, [buffer], { ms: PRIVATE_STORAGE_PUT_TIMEOUT_MS, onTimeout: () => new PrivateStorageError('unsupported') });
501
+ },
502
+ delete: async (path, scope = 'app') => {
503
+ const requestId = randomUuid();
504
+ await this.postRequest({ type: 'deletePrivateFile', requestId, scope, path }, (msg, resolve, reject) => {
505
+ if (msg.type === 'privateStorageResponse' && msg.requestId === requestId) {
506
+ if (msg.ok)
507
+ resolve(undefined);
508
+ else
509
+ reject(new PrivateStorageError(msg.error ?? 'failed'));
510
+ }
511
+ }, undefined, { ms: PRIVATE_STORAGE_TIMEOUT_MS, onTimeout: () => new PrivateStorageError('unsupported') });
512
+ },
513
+ list: async (prefix, scope = 'app') => {
514
+ const requestId = randomUuid();
515
+ return await this.postRequest({ type: 'listPrivateFiles', requestId, scope, prefix }, (msg, resolve, reject) => {
516
+ if (msg.type === 'privateStorageResponse' && msg.requestId === requestId) {
517
+ if (msg.ok)
518
+ resolve({ scope, files: msg.files ?? [] });
519
+ else
520
+ reject(new PrivateStorageError(msg.error ?? 'failed'));
521
+ }
522
+ }, undefined, { ms: PRIVATE_STORAGE_TIMEOUT_MS, onTimeout: () => new PrivateStorageError('unsupported') });
523
+ },
524
+ get: async (path, scope = 'app') => {
525
+ const requestId = randomUuid();
526
+ return await this.postRequest({ type: 'getPrivateFile', requestId, scope, path }, (msg, resolve, reject) => {
527
+ if (msg.type === 'privateStorageResponse' && msg.requestId === requestId) {
528
+ if (msg.ok && msg.data)
529
+ resolve({ data: msg.data, contentType: msg.contentType ?? '' });
530
+ else
531
+ reject(new PrivateStorageError(msg.error ?? 'failed'));
532
+ }
533
+ }, undefined, { ms: PRIVATE_STORAGE_GET_TIMEOUT_MS, onTimeout: () => new PrivateStorageError('unsupported') });
534
+ },
535
+ getLink: async (path, options) => {
536
+ validateLinkExpiresIn(options?.expiresIn);
537
+ const scope = options?.scope ?? 'app';
538
+ const requestId = randomUuid();
539
+ return await this.postRequest({
540
+ type: 'getPrivateFileLink',
541
+ requestId,
542
+ scope,
543
+ path,
544
+ ...privateFileExpiryField(options?.expiresIn),
545
+ }, (msg, resolve, reject) => {
546
+ if (msg.type === 'privateStorageResponse' && msg.requestId === requestId) {
547
+ if (msg.ok && msg.link)
548
+ resolve(msg.link);
549
+ else
550
+ reject(new PrivateStorageError(msg.error ?? 'failed'));
551
+ }
552
+ }, undefined, { ms: PRIVATE_STORAGE_TIMEOUT_MS, onTimeout: () => new PrivateStorageError('unsupported') });
553
+ },
554
+ }
555
+ });
382
556
  Object.defineProperty(this, "requestResolvers", {
383
557
  enumerable: true,
384
558
  configurable: true,
@@ -513,6 +687,18 @@ export class Connector {
513
687
  };
514
688
  this.onSettingsUpdated?.(msg.settings);
515
689
  break;
690
+ case 'appSettingsResponse':
691
+ // Handled by requestResolvers (postRequest pattern)
692
+ break;
693
+ case 'appSettingsChanged':
694
+ this.onSettingsChanged?.(msg);
695
+ break;
696
+ case 'publicStorageResponse':
697
+ // Handled by requestResolvers (postRequest pattern)
698
+ break;
699
+ case 'privateStorageResponse':
700
+ // Handled by requestResolvers (postRequest pattern)
701
+ break;
516
702
  case 'vitreSettingsUpdated':
517
703
  this.hostInformation = {
518
704
  ...this.hostInformation,
@@ -762,15 +948,26 @@ export class Connector {
762
948
  });
763
949
  }
764
950
  }
765
- async postRequest(data, handler, transfer) {
951
+ async postRequest(data, handler, transfer,
952
+ // When set, rejects with `onTimeout()` if no matching response arrives
953
+ // within `ms` — AND removes the pending resolver from
954
+ // `requestResolvers`. Without that removal a host that never answers
955
+ // (e.g. one that predates the message type) would leak the resolver
956
+ // forever, since the only other removal path is a matching response.
957
+ timeout) {
766
958
  return await new Promise((resolve, reject) => {
767
959
  let isHandled = false;
960
+ let timer;
768
961
  const handleAndResolve = (data) => {
769
962
  isHandled = true;
963
+ if (timer !== undefined)
964
+ clearTimeout(timer);
770
965
  resolve(data);
771
966
  };
772
967
  const handleAndReject = (error) => {
773
968
  isHandled = true;
969
+ if (timer !== undefined)
970
+ clearTimeout(timer);
774
971
  reject(error);
775
972
  };
776
973
  const resolver = {
@@ -785,6 +982,14 @@ export class Connector {
785
982
  },
786
983
  };
787
984
  this.requestResolvers.push(resolver);
985
+ if (timeout) {
986
+ timer = setTimeout(() => {
987
+ if (isHandled)
988
+ return;
989
+ this.requestResolvers = this.requestResolvers.filter((rr) => rr !== resolver);
990
+ handleAndReject(timeout.onTimeout());
991
+ }, timeout.ms);
992
+ }
788
993
  this.postMessage(data, transfer);
789
994
  });
790
995
  }
@@ -891,6 +1096,25 @@ export class Connector {
891
1096
  canShareStream() {
892
1097
  return typeof MediaStreamTrackProcessor !== 'undefined';
893
1098
  }
1099
+ /** Normalize `publicStorage.put`'s payload to a plain `ArrayBuffer` —
1100
+ * slicing out exactly a typed array's view (not its whole underlying
1101
+ * buffer, in case it's a subarray) so the transferred bytes match the
1102
+ * size the caller intended. */
1103
+ async toPublicFileBuffer(data) {
1104
+ if (data instanceof ArrayBuffer)
1105
+ return data;
1106
+ if (data instanceof Blob)
1107
+ return await data.arrayBuffer();
1108
+ return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
1109
+ }
1110
+ /** Same normalization as {@link toPublicFileBuffer}, for `privateStorage.put`. */
1111
+ async toPrivateFileBuffer(data) {
1112
+ if (data instanceof ArrayBuffer)
1113
+ return data;
1114
+ if (data instanceof Blob)
1115
+ return await data.arrayBuffer();
1116
+ return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
1117
+ }
894
1118
  toShareTracks(stream) {
895
1119
  const tracks = [];
896
1120
  const transfer = [];
@@ -1093,6 +1317,61 @@ export class Connector {
1093
1317
  settings,
1094
1318
  });
1095
1319
  }
1320
+ /**
1321
+ * Read the app's settings at one of the three levels — `vitre` (this
1322
+ * vitre), `team` (the vitre's team), or `space` (the space the vitre is
1323
+ * currently in). Every vitre/app instance of the team can read the same
1324
+ * value; values are JSON objects capped at 64 KB — never store secrets.
1325
+ *
1326
+ * Distinct from the legacy `settingsSchema`/`saveSettings` mechanism (see
1327
+ * {@link setSettingsSchema}, {@link saveSettings}), which is a single
1328
+ * vitre-scoped blob rendered by the host's settings form.
1329
+ *
1330
+ * Rejects with an {@link AppSettingsError} of code `'unsupported'` if the
1331
+ * host doesn't answer within 10s — a vitre host older than this feature
1332
+ * never responds to `getAppSettings`.
1333
+ */
1334
+ async getSettings(level) {
1335
+ const requestId = randomUuid();
1336
+ return await this.postRequest({ type: 'getAppSettings', requestId, level }, (msg, resolve, reject) => {
1337
+ if (msg.type === 'appSettingsResponse' && msg.requestId === requestId) {
1338
+ if (msg.ok) {
1339
+ resolve({ level: msg.level, value: msg.value ?? {}, version: msg.version ?? 0 });
1340
+ }
1341
+ else {
1342
+ reject(new AppSettingsError(msg.error ?? 'failed', level));
1343
+ }
1344
+ }
1345
+ }, undefined, { ms: APP_SETTINGS_TIMEOUT_MS, onTimeout: () => new AppSettingsError('unsupported', level) });
1346
+ }
1347
+ /**
1348
+ * Write the app's settings at `level`, with optimistic concurrency:
1349
+ * `expectedVersion` must be the version last observed for that level (from
1350
+ * {@link getSettings} or {@link onSettingsChanged}) — `0` if never
1351
+ * written. A stale version rejects with an {@link AppSettingsError} of
1352
+ * code `'conflict'`; re-read and retry. An oversized `value` (> 64 KB)
1353
+ * rejects with `'tooLarge'`.
1354
+ *
1355
+ * Rejects with code `'unsupported'` if the host doesn't answer within
1356
+ * 10s — see {@link getSettings}.
1357
+ */
1358
+ async setSettings(level, value, expectedVersion) {
1359
+ const requestId = randomUuid();
1360
+ return await this.postRequest({ type: 'setAppSettings', requestId, level, value, expectedVersion }, (msg, resolve, reject) => {
1361
+ if (msg.type === 'appSettingsResponse' && msg.requestId === requestId) {
1362
+ if (msg.ok) {
1363
+ resolve({
1364
+ level: msg.level,
1365
+ value: msg.value ?? value,
1366
+ version: msg.version ?? expectedVersion,
1367
+ });
1368
+ }
1369
+ else {
1370
+ reject(new AppSettingsError(msg.error ?? 'failed', level));
1371
+ }
1372
+ }
1373
+ }, undefined, { ms: APP_SETTINGS_TIMEOUT_MS, onTimeout: () => new AppSettingsError('unsupported', level) });
1374
+ }
1096
1375
  changeTeamSpace(space) {
1097
1376
  this.postMessage({
1098
1377
  type: 'changeTeamSpace',