@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.
- package/README.md +180 -0
- package/dist/Common/AppSettings.d.ts +34 -0
- package/dist/Common/AppSettings.js +35 -0
- package/dist/Common/AppSettings.js.map +1 -0
- package/dist/Common/Common.Model.d.ts +271 -0
- package/dist/Common/Common.Model.js.map +1 -1
- package/dist/Common/PrivateStorage.d.ts +249 -0
- package/dist/Common/PrivateStorage.js +158 -0
- package/dist/Common/PrivateStorage.js.map +1 -0
- package/dist/Common/PublicStorage.d.ts +140 -0
- package/dist/Common/PublicStorage.js +88 -0
- package/dist/Common/PublicStorage.js.map +1 -0
- package/dist/Common/index.d.ts +3 -0
- package/dist/Common/index.js +3 -0
- package/dist/Common/index.js.map +1 -1
- package/dist/CompanionConnector/CompanionConnector.Model.d.ts +11 -3
- package/dist/CompanionConnector/CompanionConnector.Model.js.map +1 -1
- package/dist/CompanionConnector/CompanionConnector.d.ts +14 -0
- package/dist/CompanionConnector/CompanionConnector.js +122 -0
- package/dist/CompanionConnector/CompanionConnector.js.map +1 -1
- package/dist/CompanionFrame/CompanionFrame.d.ts +13 -2
- package/dist/CompanionFrame/CompanionFrame.js.map +1 -1
- package/dist/Connector/Connector.Model.d.ts +29 -1
- package/dist/Connector/Connector.Model.js.map +1 -1
- package/dist/Connector/Connector.d.ts +60 -1
- package/dist/Connector/Connector.js +280 -1
- package/dist/Connector/Connector.js.map +1 -1
- package/dist/Frame/Frame.Model.d.ts +36 -2
- package/dist/Frame/Frame.Model.js.map +1 -1
- package/dist/Frame/Frame.d.ts +68 -3
- package/dist/Frame/Frame.js +326 -3
- package/dist/Frame/Frame.js.map +1 -1
- package/dist/Frame/SharedStreamPeer.d.ts +16 -0
- package/dist/Frame/SharedStreamPeer.js +74 -0
- package/dist/Frame/SharedStreamPeer.js.map +1 -0
- package/dist/Version.d.ts +1 -1
- package/dist/Version.js +1 -1
- package/dist/Version.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -155,6 +155,186 @@ getHostEnvironment() // 'native' | 'web'
|
|
|
155
155
|
|
|
156
156
|
The native Vitre injects `window.laVitreNative` into every app frame before any script runs, whatever the manifest; a Vitre in a browser or PWA and the companion leave it unset (`laVitreNative` is then `null`). Feature-detect the members you use: `io` and `serialport` depend on the app's authorizations and arrive shortly after load.
|
|
157
157
|
|
|
158
|
+
### AppSettings API — `getSettings` / `setSettings` (three levels)
|
|
159
|
+
|
|
160
|
+
Separate from the legacy `settingsSchema`/`saveSettings` mechanism above, `Connector` and `Frame` (SDK 1.54) expose a small versioned key-value API an app can read and write itself, at three levels:
|
|
161
|
+
|
|
162
|
+
```ts
|
|
163
|
+
type AppSettingsLevel = 'vitre' | 'team' | 'space'
|
|
164
|
+
|
|
165
|
+
connector.getSettings(level: AppSettingsLevel): Promise<AppSettingsValue>
|
|
166
|
+
connector.setSettings(level: AppSettingsLevel, value: Record<string, unknown>, expectedVersion: number): Promise<AppSettingsValue>
|
|
167
|
+
connector.onSettingsChanged?: (change: AppSettingsValue) => void
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
(same three members exist on `Frame`.)
|
|
171
|
+
|
|
172
|
+
- `vitre` — this vitre only.
|
|
173
|
+
- `team` — the vitre's team; every vitre/app instance of the team reads and writes the same value.
|
|
174
|
+
- `space` — the space the vitre is currently in.
|
|
175
|
+
|
|
176
|
+
`AppSettingsValue` is `{ level, value: Record<string, unknown>, version: number }`. `value` is a plain JSON object capped at **64 KB** serialized. **Never store secrets in it** — every vitre/app instance of the team can read it.
|
|
177
|
+
|
|
178
|
+
**Concurrency**: writes are optimistic-concurrency versioned. `setSettings` takes the `expectedVersion` you last observed for that level (from `getSettings` or `onSettingsChanged`); `version: 0` means the level was never written. A stale `expectedVersion` rejects with an `AppSettingsError` of code `'conflict'` — re-read and retry.
|
|
179
|
+
|
|
180
|
+
**Unsupported hosts**: a vitre host older than this feature silently ignores `getAppSettings` / `setAppSettings` and never answers. Both calls race a 10s timeout and reject with `AppSettingsError('unsupported', level)` in that case — always handle it (e.g. fall back to no-op, or to the legacy `saveSettings`).
|
|
181
|
+
|
|
182
|
+
```ts
|
|
183
|
+
import { AppSettingsError } from '@lavitre/apps/Common'
|
|
184
|
+
|
|
185
|
+
try {
|
|
186
|
+
const { value, version } = await connector.getSettings('team')
|
|
187
|
+
await connector.setSettings('team', { ...value, layout: 'grid' }, version)
|
|
188
|
+
} catch (err) {
|
|
189
|
+
if (err instanceof AppSettingsError && err.code === 'unsupported') {
|
|
190
|
+
// host predates the AppSettings API
|
|
191
|
+
} else if (err instanceof AppSettingsError && err.code === 'conflict') {
|
|
192
|
+
// someone else wrote first — re-read and retry
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
### Public storage — `publicStorage.put` / `.delete` / `.list`
|
|
198
|
+
|
|
199
|
+
`Connector` and `Frame` (SDK 1.54) expose public, **unauthenticated** file storage for the vitre's app: a place to put images, exported documents, or anything else an app wants to hand out via a stable link, without owning any storage or auth of its own.
|
|
200
|
+
|
|
201
|
+
```ts
|
|
202
|
+
type PublicStorageScope = 'app' | 'shared'
|
|
203
|
+
type PublicStoragePutOptions = { expiresIn?: number }
|
|
204
|
+
|
|
205
|
+
connector.publicStorage.put(path: string, data: ArrayBuffer | Blob | Uint8Array, contentType: string, scope?: PublicStorageScope, options?: PublicStoragePutOptions): Promise<{ path, url, size, expiresAt?, downloadUrl }>
|
|
206
|
+
connector.publicStorage.delete(path: string, scope?: PublicStorageScope): Promise<void>
|
|
207
|
+
connector.publicStorage.list(prefix?: string, scope?: PublicStorageScope): Promise<{ baseUrl: string, files: { path, url, size, expiresAt?, downloadUrl, updatedAt? }[] }>
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
(same `publicStorage` object exists on `Frame`. Not exposed on `CompanionConnector` or a companion `Frame` — only a Vitre-hosted app can write.)
|
|
211
|
+
|
|
212
|
+
**Semantics — read carefully, this is public:**
|
|
213
|
+
|
|
214
|
+
- Files go to the vitre's **TEAM** storage and are readable by **anyone without authentication** at a stable link, `https://a.lavit.re/{token}/{path}` (the token identifies the team and scope). **Never put private data here.**
|
|
215
|
+
- `scope`: `'app'` (default) is this app's own space; `'shared'` is a space every app of the team shares.
|
|
216
|
+
- Only an app running **on a vitre** can write — a companion connector/frame has no `publicStorage`.
|
|
217
|
+
- Allowed content: images (except SVG), video, audio, PDF, JSON, plain text, CSV, Markdown, Office/OpenDocument. Anything else rejects with `PublicStorageError('unsupportedType')`.
|
|
218
|
+
- **50 MB** max per file — `put` checks this locally (no round-trip) and rejects with `PublicStorageError('tooLarge')` before even sending.
|
|
219
|
+
- Overwriting an existing `path` replaces the file; readers revalidate (no caching surprises).
|
|
220
|
+
- `path` is `/`-separated segments of letters, digits, `.`, `_`, `-`; no segment may start with `.`; max 256 chars, max 8 segments. An invalid path rejects with `PublicStorageError('invalidPath')`.
|
|
221
|
+
|
|
222
|
+
`put`'s `data` is normalized to an `ArrayBuffer` and **transferred** to the host (zero-copy) — don't reuse the buffer you pass afterwards.
|
|
223
|
+
|
|
224
|
+
**Expiry — `options.expiresIn`** (SDK 1.54, seconds, opt-in): server-managed. Pass a positive integer number of seconds and the file is scheduled for deletion — the link answers 404 once it expires, and the server removes the file, no app action needed. There is **no maximum** — any positive integer works, from a few seconds to years out. Omit `expiresIn` (the default) for a permanent file; rewriting the same `path` later **without** `expiresIn` makes it permanent again (expiry isn't sticky across overwrites). An invalid value (`0`, negative, non-integer, or anything that isn't a safe integer) rejects locally, before any request is sent, with `PublicStorageError('invalidExpiry')`. The resolved `PublicFile` carries `expiresAt` (ISO UTC) only when the file has an expiry.
|
|
225
|
+
|
|
226
|
+
**Downloads — `downloadUrl`**: every `PublicFile` also carries `downloadUrl` — the same `url` with `?download=1` appended, which makes a browser download the file (under its own name) instead of navigating to it. Handy for a QR code meant to be scanned with a phone: scanning `url` opens the file in the browser, scanning `downloadUrl` downloads it straight away. Older hosts that don't send `downloadUrl` yet are covered — the SDK fills it in locally from `url`, so reading `file.downloadUrl` is always safe regardless of host version.
|
|
227
|
+
|
|
228
|
+
**Unsupported hosts**: a vitre host older than this feature silently ignores `putPublicFile` / `deletePublicFile` / `listPublicFiles` and never answers. `delete` / `list` race a 10s timeout; `put` races a longer 120s timeout (uploads take time) — both reject with `PublicStorageError('unsupported')` in that case.
|
|
229
|
+
|
|
230
|
+
```ts
|
|
231
|
+
import { PublicStorageError } from '@lavitre/apps/Common'
|
|
232
|
+
|
|
233
|
+
try {
|
|
234
|
+
const { url } = await connector.publicStorage.put('exports/report.pdf', pdfBytes, 'application/pdf')
|
|
235
|
+
connector.shareData(url)
|
|
236
|
+
} catch (err) {
|
|
237
|
+
if (err instanceof PublicStorageError && err.code === 'tooLarge') {
|
|
238
|
+
// over 50 MB — shrink it or split it up
|
|
239
|
+
} else if (err instanceof PublicStorageError && err.code === 'unsupported') {
|
|
240
|
+
// host predates the public storage API
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
**Example — photo → QR code.** Capture a still from the local camera with `LocalPreview`, upload it with a 1-hour expiry, and show its `downloadUrl` as a QR code for a phone to scan:
|
|
246
|
+
|
|
247
|
+
```ts
|
|
248
|
+
import { LocalPreview } from '@lavitre/apps/Frame'
|
|
249
|
+
|
|
250
|
+
const preview = new LocalPreview(frame)
|
|
251
|
+
const jpeg = await preview.capture() // Blob
|
|
252
|
+
|
|
253
|
+
const { downloadUrl } = await frame.publicStorage.put(
|
|
254
|
+
`photos/${crypto.randomUUID()}.jpg`,
|
|
255
|
+
jpeg,
|
|
256
|
+
'image/jpeg',
|
|
257
|
+
'app',
|
|
258
|
+
{ expiresIn: 3600 }, // gone after 1 hour
|
|
259
|
+
)
|
|
260
|
+
|
|
261
|
+
// Render `downloadUrl` as a QR code with any QR library you like (the SDK
|
|
262
|
+
// doesn't ship one, to avoid forcing a dependency on apps that don't need it).
|
|
263
|
+
renderQrCode(downloadUrl)
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
A random, unguessable file name (`crypto.randomUUID()`) matters here: the file is on a **public, unauthenticated** link — anyone with the URL can view it, and search engines or other visitors could stumble onto a guessable one. Combine that with a short `expiresIn` whenever the photo shows an identifiable person, and avoid predictable paths (`photos/1.jpg`, `photos/latest.jpg`) for anything you wouldn't want to stay public indefinitely.
|
|
267
|
+
|
|
268
|
+
### Private storage — `privateStorage.put` / `.delete` / `.list` / `.get` / `.getLink`
|
|
269
|
+
|
|
270
|
+
`Connector` and `Frame` (SDK 1.56) expose private file storage for the vitre's app: a place to put anything that should NOT be world-readable — recordings, documents, exports — while still being shareable, on purpose, for a short time.
|
|
271
|
+
|
|
272
|
+
```ts
|
|
273
|
+
type PrivateStorageScope = 'app' | 'shared'
|
|
274
|
+
type PrivateStoragePutOptions = { expiresIn?: number }
|
|
275
|
+
type PrivateStorageGetLinkOptions = { scope?: PrivateStorageScope; expiresIn?: number }
|
|
276
|
+
|
|
277
|
+
connector.privateStorage.put(path: string, data: ArrayBuffer | Blob | Uint8Array, contentType: string, scope?: PrivateStorageScope, options?: PrivateStoragePutOptions): Promise<{ path, size, contentType, expiresAt?, updatedAt? }>
|
|
278
|
+
connector.privateStorage.delete(path: string, scope?: PrivateStorageScope): Promise<void>
|
|
279
|
+
connector.privateStorage.list(prefix?: string, scope?: PrivateStorageScope): Promise<{ scope, files: { path, size, contentType, expiresAt?, updatedAt? }[] }>
|
|
280
|
+
connector.privateStorage.get(path: string, scope?: PrivateStorageScope): Promise<{ data: ArrayBuffer, contentType: string }>
|
|
281
|
+
connector.privateStorage.getLink(path: string, options?: PrivateStorageGetLinkOptions): Promise<{ url, downloadUrl, expiresAt }>
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
(same `privateStorage` object exists on `Frame`. `CompanionConnector` and a companion `Frame` also have `privateStorage`, but trimmed to `list`/`get`/`getLink` — see below.)
|
|
285
|
+
|
|
286
|
+
**Semantics:**
|
|
287
|
+
|
|
288
|
+
- Files go to the vitre's **TEAM** storage, same as public storage, but have **no public link**. There is no stable `url` on a `PrivateFile` — reading requires either a host round-trip (`get`) or a temporary signed link (`getLink`).
|
|
289
|
+
- **Who can read**: any vitre or companion **of the team** (once the host implements the read path) — not an anonymous visitor. **Who can write**: only an app running **on a vitre**. `put` / `delete` are not exposed on `CompanionConnector` or a companion `Frame` at all (not even as a no-op) — a companion app only has `list` / `get` / `getLink`.
|
|
290
|
+
- `scope`: `'app'` (default) is this app's own space; `'shared'` is a space every app of the team shares — same split as public storage.
|
|
291
|
+
- Unlike public storage, **any content type** is accepted on write — nothing here is ever served publicly as-is, so there's no allowlist to enforce.
|
|
292
|
+
- **50 MB** max per file — `put` checks this locally (no round-trip) and rejects with `PrivateStorageError('tooLarge')` before even sending.
|
|
293
|
+
- `path` follows the same rule as public storage (`/`-separated segments of letters, digits, `.`, `_`, `-`; no segment may start with `.`; max 256 chars, max 8 segments) — also checked locally, rejecting with `PrivateStorageError('invalidPath')` before any request is sent.
|
|
294
|
+
- Overwriting an existing `path` replaces the file; readers revalidate.
|
|
295
|
+
|
|
296
|
+
`put`'s `data` is normalized to an `ArrayBuffer` and **transferred** to the host (zero-copy) — don't reuse the buffer you pass afterwards.
|
|
297
|
+
|
|
298
|
+
**`get` vs `getLink`**: `get` round-trips the file's bytes back through the host into this app — no link, no expiry to think about, but every byte crosses the host boundary (use `PRIVATE_STORAGE_GET_TIMEOUT_MS`-worthy patience for a big file). `getLink` instead mints a **temporary signed link** — a URL that works like a public-storage link (openable in a browser, or forced to download with `?download=1` / `.downloadUrl`) but only until it expires: **1 hour by default**, capped at **7 days** (`options.expiresIn`, seconds — an SDK-local check rejects anything over the cap with `PrivateStorageError('invalidExpiry')` before any request is sent). A link also dies early — answers 404 — the moment the underlying file is deleted or itself expires, whichever comes first. Use `getLink` whenever the consumer is outside your app's own iframe (another device, a QR code, a phone's browser); use `get` when you just need the bytes in-process.
|
|
299
|
+
|
|
300
|
+
**Expiry — `options.expiresIn`** on `put` (seconds, opt-in): exactly like public storage's file expiry — a positive integer schedules the file for deletion (no maximum), omitting it keeps the file permanent, and rewriting the same `path` later without `expiresIn` makes it permanent again. This is the file's own lifetime, independent of any link's shorter `expiresIn` minted against it.
|
|
301
|
+
|
|
302
|
+
**Unsupported hosts**: a vitre host older than this feature silently ignores every `*PrivateFile*` message and never answers. `delete` / `list` / `getLink` race a 10s timeout; `put` and `get` race a longer 120s timeout (moving bytes takes time) — all reject with `PrivateStorageError('unsupported')` in that case. A companion host that knows about private storage but was asked to `put`/`delete` anyway (bypassing the SDK's type-level omission) answers with the same `'unsupported'` code over the wire instead of timing out.
|
|
303
|
+
|
|
304
|
+
```ts
|
|
305
|
+
import { PrivateStorageError } from '@lavitre/apps/Common'
|
|
306
|
+
|
|
307
|
+
try {
|
|
308
|
+
const { path } = await connector.privateStorage.put('recordings/standup.webm', recordingBytes, 'video/webm')
|
|
309
|
+
const { downloadUrl } = await connector.privateStorage.getLink(path, { expiresIn: 24 * 3600 }) // 24h
|
|
310
|
+
renderQrCode(downloadUrl)
|
|
311
|
+
} catch (err) {
|
|
312
|
+
if (err instanceof PrivateStorageError && err.code === 'tooLarge') {
|
|
313
|
+
// over 50 MB
|
|
314
|
+
} else if (err instanceof PrivateStorageError && err.code === 'unsupported') {
|
|
315
|
+
// host predates the private storage API
|
|
316
|
+
}
|
|
317
|
+
}
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
**Example — share a recording for 24h via QR code.** Store a recording privately (nobody but the team can reach it), then mint a 24-hour signed link and render it as a QR code for a phone to scan:
|
|
321
|
+
|
|
322
|
+
```ts
|
|
323
|
+
const { path } = await frame.privateStorage.put(
|
|
324
|
+
`recordings/${crypto.randomUUID()}.webm`,
|
|
325
|
+
recordingBlob,
|
|
326
|
+
'video/webm',
|
|
327
|
+
)
|
|
328
|
+
|
|
329
|
+
const { downloadUrl } = await frame.privateStorage.getLink(path, { expiresIn: 24 * 60 * 60 }) // 24h, max 7 days
|
|
330
|
+
|
|
331
|
+
// Render `downloadUrl` as a QR code with any QR library you like (the SDK
|
|
332
|
+
// doesn't ship one, to avoid forcing a dependency on apps that don't need it).
|
|
333
|
+
renderQrCode(downloadUrl)
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
Unlike the public-storage photo example, there's no need for a random path *for secrecy* here (the file was already private before `getLink` was ever called) — `crypto.randomUUID()` above is just a convenient collision-free name. The signed link itself is the only thing that grants temporary, unauthenticated access; let it expire, or explicitly `delete` the file, once the recording no longer needs to be shared.
|
|
337
|
+
|
|
158
338
|
## Development
|
|
159
339
|
|
|
160
340
|
`pnpm typecheck`, `pnpm build`, and `pnpm test` for the unit tests (`node:test`; Node ≥ 22.18 runs the TypeScript directly).
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import type { AppSettingsLevel } from './Common.Model.js';
|
|
2
|
+
/**
|
|
3
|
+
* Error codes for the AppSettings API (`Connector.getSettings` /
|
|
4
|
+
* `setSettings`, `Frame.getSettings` / `setSettings`).
|
|
5
|
+
*
|
|
6
|
+
* The five wire codes — `conflict`, `tooLarge`, `invalid`, `unavailable`,
|
|
7
|
+
* `failed` — come straight from the host's `appSettingsResponse.error`.
|
|
8
|
+
* `unsupported` is synthesized locally by the SDK when no response arrives
|
|
9
|
+
* within {@link APP_SETTINGS_TIMEOUT_MS}: the signature of a vitre host that
|
|
10
|
+
* predates this feature, which silently ignores the unknown `getAppSettings`
|
|
11
|
+
* / `setAppSettings` message types instead of answering.
|
|
12
|
+
*/
|
|
13
|
+
export type AppSettingsErrorCode = 'conflict' | 'tooLarge' | 'invalid' | 'unavailable' | 'failed' | 'unsupported';
|
|
14
|
+
/**
|
|
15
|
+
* Thrown by `getSettings` / `setSettings` when the host answers with
|
|
16
|
+
* `ok: false`, or when the request times out (see {@link AppSettingsErrorCode}).
|
|
17
|
+
*/
|
|
18
|
+
export declare class AppSettingsError extends Error {
|
|
19
|
+
readonly code: AppSettingsErrorCode;
|
|
20
|
+
readonly level: AppSettingsLevel;
|
|
21
|
+
constructor(code: AppSettingsErrorCode, level: AppSettingsLevel);
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* How long `getSettings` / `setSettings` wait for `appSettingsResponse`
|
|
25
|
+
* before treating the host as not supporting the AppSettings API.
|
|
26
|
+
*
|
|
27
|
+
* Passed as `Connector`/`Frame`'s private `postRequest(..., timeout)` 4th
|
|
28
|
+
* argument, which both answers with `onTimeout()` AND removes the pending
|
|
29
|
+
* resolver from `requestResolvers` when the timer fires — a host that
|
|
30
|
+
* predates this feature never answers, so without that removal the
|
|
31
|
+
* resolver would sit there forever (fixed alongside the public storage API,
|
|
32
|
+
* which uses the same `postRequest(..., timeout)` mechanism).
|
|
33
|
+
*/
|
|
34
|
+
export declare const APP_SETTINGS_TIMEOUT_MS = 10000;
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Thrown by `getSettings` / `setSettings` when the host answers with
|
|
3
|
+
* `ok: false`, or when the request times out (see {@link AppSettingsErrorCode}).
|
|
4
|
+
*/
|
|
5
|
+
export class AppSettingsError extends Error {
|
|
6
|
+
constructor(code, level) {
|
|
7
|
+
super(`AppSettings '${level}' request failed: ${code}`);
|
|
8
|
+
Object.defineProperty(this, "code", {
|
|
9
|
+
enumerable: true,
|
|
10
|
+
configurable: true,
|
|
11
|
+
writable: true,
|
|
12
|
+
value: code
|
|
13
|
+
});
|
|
14
|
+
Object.defineProperty(this, "level", {
|
|
15
|
+
enumerable: true,
|
|
16
|
+
configurable: true,
|
|
17
|
+
writable: true,
|
|
18
|
+
value: level
|
|
19
|
+
});
|
|
20
|
+
this.name = 'AppSettingsError';
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* How long `getSettings` / `setSettings` wait for `appSettingsResponse`
|
|
25
|
+
* before treating the host as not supporting the AppSettings API.
|
|
26
|
+
*
|
|
27
|
+
* Passed as `Connector`/`Frame`'s private `postRequest(..., timeout)` 4th
|
|
28
|
+
* argument, which both answers with `onTimeout()` AND removes the pending
|
|
29
|
+
* resolver from `requestResolvers` when the timer fires — a host that
|
|
30
|
+
* predates this feature never answers, so without that removal the
|
|
31
|
+
* resolver would sit there forever (fixed alongside the public storage API,
|
|
32
|
+
* which uses the same `postRequest(..., timeout)` mechanism).
|
|
33
|
+
*/
|
|
34
|
+
export const APP_SETTINGS_TIMEOUT_MS = 10000;
|
|
35
|
+
//# sourceMappingURL=AppSettings.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"AppSettings.js","sourceRoot":"","sources":["../../Common/AppSettings.ts"],"names":[],"mappings":"AAqBA;;;GAGG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC,YACkB,IAA0B,EAC1B,KAAuB;QAEvC,KAAK,CAAC,gBAAgB,KAAK,qBAAqB,IAAI,EAAE,CAAC,CAAA;QAHvD;;;;mBAAgB,IAAI;WAAsB;QAC1C;;;;mBAAgB,KAAK;WAAkB;QAGvC,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAA;IAChC,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,KAAK,CAAA","sourcesContent":["import type { AppSettingsLevel } from './Common.Model.js'\n\n/**\n * Error codes for the AppSettings API (`Connector.getSettings` /\n * `setSettings`, `Frame.getSettings` / `setSettings`).\n *\n * The five wire codes — `conflict`, `tooLarge`, `invalid`, `unavailable`,\n * `failed` — come straight from the host's `appSettingsResponse.error`.\n * `unsupported` is synthesized locally by the SDK when no response arrives\n * within {@link APP_SETTINGS_TIMEOUT_MS}: the signature of a vitre host that\n * predates this feature, which silently ignores the unknown `getAppSettings`\n * / `setAppSettings` message types instead of answering.\n */\nexport type AppSettingsErrorCode =\n | 'conflict'\n | 'tooLarge'\n | 'invalid'\n | 'unavailable'\n | 'failed'\n | 'unsupported'\n\n/**\n * Thrown by `getSettings` / `setSettings` when the host answers with\n * `ok: false`, or when the request times out (see {@link AppSettingsErrorCode}).\n */\nexport class AppSettingsError extends Error {\n constructor(\n public readonly code: AppSettingsErrorCode,\n public readonly level: AppSettingsLevel,\n ) {\n super(`AppSettings '${level}' request failed: ${code}`)\n this.name = 'AppSettingsError'\n }\n}\n\n/**\n * How long `getSettings` / `setSettings` wait for `appSettingsResponse`\n * before treating the host as not supporting the AppSettings API.\n *\n * Passed as `Connector`/`Frame`'s private `postRequest(..., timeout)` 4th\n * argument, which both answers with `onTimeout()` AND removes the pending\n * resolver from `requestResolvers` when the timer fires — a host that\n * predates this feature never answers, so without that removal the\n * resolver would sit there forever (fixed alongside the public storage API,\n * which uses the same `postRequest(..., timeout)` mechanism).\n */\nexport const APP_SETTINGS_TIMEOUT_MS = 10000\n"]}
|
|
@@ -808,6 +808,277 @@ export type SaveSettings = {
|
|
|
808
808
|
export type SettingsUpdated = {
|
|
809
809
|
settings: any;
|
|
810
810
|
};
|
|
811
|
+
/**
|
|
812
|
+
* SDK 1.52 — the three levels of the AppSettings API (`Connector.getSettings`
|
|
813
|
+
* / `setSettings`, `Frame.getSettings` / `setSettings`):
|
|
814
|
+
* - `vitre` — this vitre only.
|
|
815
|
+
* - `team` — the vitre's team, shared by every vitre/app instance in it.
|
|
816
|
+
* - `space` — the space the vitre is currently in.
|
|
817
|
+
*
|
|
818
|
+
* Distinct from the legacy per-app `settingsSchema`/`saveSettings`/
|
|
819
|
+
* `onSettingsUpdated` mechanism (a single, vitre-scoped JSON blob rendered by
|
|
820
|
+
* the host's settings form) — the AppSettings API is app-driven, versioned,
|
|
821
|
+
* and readable/writable at any of the three levels.
|
|
822
|
+
*/
|
|
823
|
+
export type AppSettingsLevel = 'vitre' | 'team' | 'space';
|
|
824
|
+
/**
|
|
825
|
+
* A JSON object of app settings at one `level`, with the optimistic-
|
|
826
|
+
* concurrency `version` it was read/written at. `version` is `0` when the
|
|
827
|
+
* level was never written. Max 64 KB serialized. Never store secrets —
|
|
828
|
+
* every vitre/app instance of the team can read it.
|
|
829
|
+
*/
|
|
830
|
+
export type AppSettingsValue = {
|
|
831
|
+
level: AppSettingsLevel;
|
|
832
|
+
value: Record<string, unknown>;
|
|
833
|
+
version: number;
|
|
834
|
+
};
|
|
835
|
+
/** App → host: read the app's settings at `level`. Answered by `AppSettingsResponse`. */
|
|
836
|
+
export type GetAppSettings = {
|
|
837
|
+
requestId: string;
|
|
838
|
+
level: AppSettingsLevel;
|
|
839
|
+
};
|
|
840
|
+
/**
|
|
841
|
+
* App → host: write the app's settings at `level`. `expectedVersion` must be
|
|
842
|
+
* the version last observed for that level (via `AppSettingsResponse` or
|
|
843
|
+
* `AppSettingsChanged`) — `0` if never written. A stale `expectedVersion`
|
|
844
|
+
* fails with `AppSettingsResponse.error === 'conflict'`.
|
|
845
|
+
*/
|
|
846
|
+
export type SetAppSettings = {
|
|
847
|
+
requestId: string;
|
|
848
|
+
level: AppSettingsLevel;
|
|
849
|
+
value: Record<string, unknown>;
|
|
850
|
+
expectedVersion: number;
|
|
851
|
+
};
|
|
852
|
+
/** Host → app: reply to `GetAppSettings` / `SetAppSettings`, matched by `requestId`. */
|
|
853
|
+
export type AppSettingsResponse = {
|
|
854
|
+
requestId: string;
|
|
855
|
+
level: AppSettingsLevel;
|
|
856
|
+
ok: boolean;
|
|
857
|
+
value?: Record<string, unknown>;
|
|
858
|
+
version?: number;
|
|
859
|
+
error?: 'conflict' | 'tooLarge' | 'invalid' | 'unavailable' | 'failed';
|
|
860
|
+
};
|
|
861
|
+
/**
|
|
862
|
+
* Host → app: pushed whenever the settings at `level` change — including
|
|
863
|
+
* changes this app itself made with `setSettings`, and changes made by
|
|
864
|
+
* another vitre/app instance sharing the same team/space.
|
|
865
|
+
*/
|
|
866
|
+
export type AppSettingsChanged = AppSettingsValue;
|
|
867
|
+
/**
|
|
868
|
+
* SDK 1.53 — scope for the public storage API (`Connector.publicStorage` /
|
|
869
|
+
* `Frame.publicStorage`):
|
|
870
|
+
* - `app` — this app's own space in the vitre's public storage.
|
|
871
|
+
* - `shared` — a space all the team's apps share.
|
|
872
|
+
*
|
|
873
|
+
* Files in either scope go to the vitre's TEAM storage and are readable by
|
|
874
|
+
* ANYONE without authentication at the returned `url` — never store private
|
|
875
|
+
* data there. Only a Vitre-hosted app can write (a companion connector has
|
|
876
|
+
* no `publicStorage`).
|
|
877
|
+
*/
|
|
878
|
+
export type PublicStorageScope = 'app' | 'shared';
|
|
879
|
+
/**
|
|
880
|
+
* App → host: upload (or overwrite) a file in public storage. Media and
|
|
881
|
+
* documents only (images except SVG, video, audio, PDF, JSON, plain text,
|
|
882
|
+
* CSV, Markdown, Office/OpenDocument); 50 MB max. Overwriting an existing
|
|
883
|
+
* `path` replaces the file (readers revalidate). Answered by
|
|
884
|
+
* `PublicStorageResponse`.
|
|
885
|
+
*
|
|
886
|
+
* `expiresIn` (SDK 1.54) is optional, in seconds — validated locally by the
|
|
887
|
+
* SDK (`validateExpiresIn`) before this message is even sent. Omitted when
|
|
888
|
+
* not requested; a host that predates this field ignores it. The vitre host
|
|
889
|
+
* relays it to the server, which deletes the file once it elapses.
|
|
890
|
+
*/
|
|
891
|
+
export type PutPublicFile = {
|
|
892
|
+
requestId: string;
|
|
893
|
+
scope: PublicStorageScope;
|
|
894
|
+
path: string;
|
|
895
|
+
contentType: string;
|
|
896
|
+
data: ArrayBuffer;
|
|
897
|
+
expiresIn?: number;
|
|
898
|
+
};
|
|
899
|
+
/** App → host: delete a file from public storage. Answered by `PublicStorageResponse`. */
|
|
900
|
+
export type DeletePublicFile = {
|
|
901
|
+
requestId: string;
|
|
902
|
+
scope: PublicStorageScope;
|
|
903
|
+
path: string;
|
|
904
|
+
};
|
|
905
|
+
/**
|
|
906
|
+
* App → host: list files in `scope`, optionally filtered to paths starting
|
|
907
|
+
* with `prefix`. Answered by `PublicStorageResponse`.
|
|
908
|
+
*/
|
|
909
|
+
export type ListPublicFiles = {
|
|
910
|
+
requestId: string;
|
|
911
|
+
scope: PublicStorageScope;
|
|
912
|
+
prefix?: string;
|
|
913
|
+
};
|
|
914
|
+
/**
|
|
915
|
+
* A file written to public storage. `url` is the stable, unauthenticated
|
|
916
|
+
* link.
|
|
917
|
+
*
|
|
918
|
+
* `expiresAt` (SDK 1.54, ISO UTC) is present only when the file was
|
|
919
|
+
* `put` with `expiresIn` — the link answers 404 and the server deletes the
|
|
920
|
+
* file once this instant passes. Absent for a permanent file.
|
|
921
|
+
*
|
|
922
|
+
* `downloadUrl` (SDK 1.54) is `url` with `?download=1`, forcing a browser
|
|
923
|
+
* download with the file's name instead of navigating to it — handy for a
|
|
924
|
+
* QR code pointed at by a phone. The host may omit it (older hosts); when
|
|
925
|
+
* absent the SDK fills it locally from `url` (see `withDownloadUrlFallback`),
|
|
926
|
+
* so apps can always read `downloadUrl` regardless of host version.
|
|
927
|
+
*/
|
|
928
|
+
export type PublicFile = {
|
|
929
|
+
path: string;
|
|
930
|
+
url: string;
|
|
931
|
+
size: number;
|
|
932
|
+
expiresAt?: string;
|
|
933
|
+
downloadUrl?: string;
|
|
934
|
+
};
|
|
935
|
+
/** One entry returned by `listPublicFiles`. */
|
|
936
|
+
export type PublicFileEntry = PublicFile & {
|
|
937
|
+
updatedAt?: string;
|
|
938
|
+
};
|
|
939
|
+
/**
|
|
940
|
+
* Host → app: reply to `PutPublicFile` / `DeletePublicFile` / `ListPublicFiles`,
|
|
941
|
+
* matched by `requestId`. `file` answers a put, `files`/`baseUrl` answer a list.
|
|
942
|
+
*/
|
|
943
|
+
export type PublicStorageResponse = {
|
|
944
|
+
requestId: string;
|
|
945
|
+
ok: boolean;
|
|
946
|
+
url?: string;
|
|
947
|
+
file?: PublicFile;
|
|
948
|
+
files?: PublicFileEntry[];
|
|
949
|
+
baseUrl?: string;
|
|
950
|
+
error?: 'tooLarge' | 'unsupportedType' | 'invalidPath' | 'storageNotConfigured' | 'unavailable' | 'failed';
|
|
951
|
+
};
|
|
952
|
+
/** Result of `publicStorage.list` — every app/vitre instance of the team sees the same files. */
|
|
953
|
+
export type PublicStorageListResult = {
|
|
954
|
+
baseUrl: string;
|
|
955
|
+
files: PublicFileEntry[];
|
|
956
|
+
};
|
|
957
|
+
/**
|
|
958
|
+
* SDK 1.56 — scope for the private storage API (`Connector.privateStorage`
|
|
959
|
+
* / `Frame.privateStorage` / `CompanionConnector.privateStorage` /
|
|
960
|
+
* `CompanionFrame.privateStorage`). Identical values to
|
|
961
|
+
* `PublicStorageScope` — aliased rather than redefined.
|
|
962
|
+
*
|
|
963
|
+
* Unlike public storage, files in either scope have NO public link: they
|
|
964
|
+
* are readable by any vitre or companion of the team (via `get` or a
|
|
965
|
+
* temporary `getLink` signed link), never by an anonymous visitor. Only a
|
|
966
|
+
* Vitre-hosted app can write (`put`/`delete`) — a companion connector/frame
|
|
967
|
+
* only has `list`/`get`/`getLink`.
|
|
968
|
+
*/
|
|
969
|
+
export type PrivateStorageScope = PublicStorageScope;
|
|
970
|
+
/**
|
|
971
|
+
* App → host: upload (or overwrite) a file in private storage. Any content
|
|
972
|
+
* type is accepted — nothing here is ever served publicly as-is; 50 MB max.
|
|
973
|
+
* Overwriting an existing `path` replaces the file (readers revalidate).
|
|
974
|
+
* Vitre-only — the companion host answers with `error: 'unsupported'`.
|
|
975
|
+
* Answered by `PrivateStorageResponse`.
|
|
976
|
+
*
|
|
977
|
+
* `expiresIn` is optional, in seconds — validated locally by the SDK
|
|
978
|
+
* (`validatePrivateExpiresIn`) before this message is even sent. Omitted
|
|
979
|
+
* when not requested, which keeps the file permanent.
|
|
980
|
+
*/
|
|
981
|
+
export type PutPrivateFile = {
|
|
982
|
+
requestId: string;
|
|
983
|
+
scope: PrivateStorageScope;
|
|
984
|
+
path: string;
|
|
985
|
+
contentType: string;
|
|
986
|
+
data: ArrayBuffer;
|
|
987
|
+
expiresIn?: number;
|
|
988
|
+
};
|
|
989
|
+
/**
|
|
990
|
+
* App → host: delete a file from private storage. Resolves even if the
|
|
991
|
+
* path didn't exist. Vitre-only — the companion host answers with
|
|
992
|
+
* `error: 'unsupported'`. Answered by `PrivateStorageResponse`.
|
|
993
|
+
*/
|
|
994
|
+
export type DeletePrivateFile = {
|
|
995
|
+
requestId: string;
|
|
996
|
+
scope: PrivateStorageScope;
|
|
997
|
+
path: string;
|
|
998
|
+
};
|
|
999
|
+
/**
|
|
1000
|
+
* App → host: list files in `scope`, optionally filtered to paths starting
|
|
1001
|
+
* with `prefix`. Expired files are omitted. Answered by
|
|
1002
|
+
* `PrivateStorageResponse`.
|
|
1003
|
+
*/
|
|
1004
|
+
export type ListPrivateFiles = {
|
|
1005
|
+
requestId: string;
|
|
1006
|
+
scope: PrivateStorageScope;
|
|
1007
|
+
prefix?: string;
|
|
1008
|
+
};
|
|
1009
|
+
/**
|
|
1010
|
+
* App → host: download the bytes of a private file. Answered by
|
|
1011
|
+
* `PrivateStorageResponse` (`data` + `contentType`), or
|
|
1012
|
+
* `error: 'notFound'` if the path doesn't exist or has expired.
|
|
1013
|
+
*/
|
|
1014
|
+
export type GetPrivateFile = {
|
|
1015
|
+
requestId: string;
|
|
1016
|
+
scope: PrivateStorageScope;
|
|
1017
|
+
path: string;
|
|
1018
|
+
};
|
|
1019
|
+
/**
|
|
1020
|
+
* App → host: mint a temporary signed link to a private file — readable
|
|
1021
|
+
* without authentication for `expiresIn` seconds (host default 3600, max
|
|
1022
|
+
* 604800 — validated locally by the SDK, `validateLinkExpiresIn`), or until
|
|
1023
|
+
* the file itself is deleted/expires, whichever comes first. Answered by
|
|
1024
|
+
* `PrivateStorageResponse` (`link`), or `error: 'notFound'` if the path
|
|
1025
|
+
* doesn't exist or has expired.
|
|
1026
|
+
*/
|
|
1027
|
+
export type GetPrivateFileLink = {
|
|
1028
|
+
requestId: string;
|
|
1029
|
+
scope: PrivateStorageScope;
|
|
1030
|
+
path: string;
|
|
1031
|
+
expiresIn?: number;
|
|
1032
|
+
};
|
|
1033
|
+
/**
|
|
1034
|
+
* A file in private storage. Unlike `PublicFile` there is no stable `url` —
|
|
1035
|
+
* private files have no public link; use `getLink` for a temporary signed
|
|
1036
|
+
* one.
|
|
1037
|
+
*
|
|
1038
|
+
* `expiresAt` (ISO UTC) is present only when the file was `put` with
|
|
1039
|
+
* `expiresIn`. Absent for a permanent file.
|
|
1040
|
+
*/
|
|
1041
|
+
export type PrivateFile = {
|
|
1042
|
+
path: string;
|
|
1043
|
+
size: number;
|
|
1044
|
+
contentType: string;
|
|
1045
|
+
updatedAt?: string;
|
|
1046
|
+
expiresAt?: string;
|
|
1047
|
+
};
|
|
1048
|
+
/**
|
|
1049
|
+
* A temporary signed link to a private file, from `getLink`. `url` opens
|
|
1050
|
+
* the file inline (when its content type is allowlisted) or downloads it;
|
|
1051
|
+
* `downloadUrl` is the same link forcing a download under the file's name
|
|
1052
|
+
* (`?download=1`), handy for a QR code. Dies at `expiresAt`, or earlier if
|
|
1053
|
+
* the underlying file is deleted or itself expires first.
|
|
1054
|
+
*/
|
|
1055
|
+
export type PrivateFileLink = {
|
|
1056
|
+
url: string;
|
|
1057
|
+
downloadUrl: string;
|
|
1058
|
+
expiresAt: string;
|
|
1059
|
+
};
|
|
1060
|
+
/**
|
|
1061
|
+
* Host → app: reply to `PutPrivateFile` / `DeletePrivateFile` /
|
|
1062
|
+
* `ListPrivateFiles` / `GetPrivateFile` / `GetPrivateFileLink`, matched by
|
|
1063
|
+
* `requestId`. `file` answers a put, `files` answers a list, `data` +
|
|
1064
|
+
* `contentType` answer a get (`data` is an `ArrayBuffer`, transferred),
|
|
1065
|
+
* `link` answers a getLink.
|
|
1066
|
+
*/
|
|
1067
|
+
export type PrivateStorageResponse = {
|
|
1068
|
+
requestId: string;
|
|
1069
|
+
ok: boolean;
|
|
1070
|
+
file?: PrivateFile;
|
|
1071
|
+
files?: PrivateFile[];
|
|
1072
|
+
data?: ArrayBuffer;
|
|
1073
|
+
contentType?: string;
|
|
1074
|
+
link?: PrivateFileLink;
|
|
1075
|
+
error?: 'tooLarge' | 'invalidPath' | 'storageNotConfigured' | 'notFound' | 'unavailable' | 'failed';
|
|
1076
|
+
};
|
|
1077
|
+
/** Result of `privateStorage.list`. */
|
|
1078
|
+
export type PrivateStorageListResult = {
|
|
1079
|
+
scope: PrivateStorageScope;
|
|
1080
|
+
files: PrivateFile[];
|
|
1081
|
+
};
|
|
811
1082
|
export type ChangeTeamSpace = {
|
|
812
1083
|
space: string;
|
|
813
1084
|
};
|