@lavitre/apps 1.55.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.
@@ -0,0 +1,249 @@
1
+ import type { PrivateFile, PrivateFileLink, PrivateStorageListResult, PrivateStorageScope } from './Common.Model.js';
2
+ /**
3
+ * Error codes for the private storage API (`Connector.privateStorage` /
4
+ * `Frame.privateStorage` / `CompanionConnector.privateStorage` /
5
+ * `CompanionFrame.privateStorage`).
6
+ *
7
+ * The six wire codes — `tooLarge`, `invalidPath`, `storageNotConfigured`,
8
+ * `notFound`, `unavailable`, `failed` — come straight from the host's
9
+ * `privateStorageResponse.error`. `unsupported` and `invalidExpiry` are
10
+ * synthesized locally by the SDK, never sent by the host:
11
+ * - `unsupported` fires when no response arrives within the request's
12
+ * timeout (see {@link PRIVATE_STORAGE_TIMEOUT_MS} /
13
+ * {@link PRIVATE_STORAGE_PUT_TIMEOUT_MS} /
14
+ * {@link PRIVATE_STORAGE_GET_TIMEOUT_MS}) — the signature of a host that
15
+ * predates this feature, which silently ignores the unknown
16
+ * `putPrivateFile` / `deletePrivateFile` / `listPrivateFiles` /
17
+ * `getPrivateFile` / `getPrivateFileLink` message types instead of
18
+ * answering. A companion host that KNOWS about private storage but
19
+ * doesn't support writes answers `putPrivateFile` / `deletePrivateFile`
20
+ * with this same code over the wire instead (see
21
+ * `CompanionConnector`/`CompanionFrame`, which don't even expose
22
+ * `put`/`delete` at the type level).
23
+ * - `invalidExpiry` fires when `put`'s `options.expiresIn`, or `getLink`'s
24
+ * `options.expiresIn`, isn't a positive safe integer — or, for `getLink`,
25
+ * exceeds {@link MAX_PRIVATE_LINK_EXPIRES_IN_SECONDS} — see
26
+ * {@link validatePrivateExpiresIn} / {@link validateLinkExpiresIn}.
27
+ * Rejected before any request is sent.
28
+ */
29
+ export type PrivateStorageErrorCode = 'tooLarge' | 'invalidPath' | 'invalidExpiry' | 'storageNotConfigured' | 'notFound' | 'unsupported' | 'unavailable' | 'failed';
30
+ /**
31
+ * Thrown by `privateStorage.put` / `.delete` / `.list` / `.get` / `.getLink`
32
+ * when the host answers with `ok: false`, when the request times out, or
33
+ * locally (without a round-trip) when the payload exceeds
34
+ * {@link MAX_PRIVATE_FILE_SIZE_BYTES}, the `path` fails
35
+ * {@link validatePrivatePath}, or an `expiresIn` fails validation — see
36
+ * {@link PrivateStorageErrorCode}.
37
+ */
38
+ export declare class PrivateStorageError extends Error {
39
+ readonly code: PrivateStorageErrorCode;
40
+ constructor(code: PrivateStorageErrorCode);
41
+ }
42
+ /**
43
+ * How long `privateStorage.delete` / `.list` / `.getLink` wait for
44
+ * `privateStorageResponse` before treating the host as not supporting the
45
+ * private storage API. Passed as `Connector`/`Frame`/`CompanionConnector`'s
46
+ * private `postRequest(..., timeout)` 4th argument, which removes the
47
+ * pending resolver when the timer fires (same fix as
48
+ * {@link PUBLIC_STORAGE_TIMEOUT_MS} in `PublicStorage.ts` — see its doc
49
+ * comment).
50
+ */
51
+ export declare const PRIVATE_STORAGE_TIMEOUT_MS = 10000;
52
+ /**
53
+ * `privateStorage.put` waits longer than {@link PRIVATE_STORAGE_TIMEOUT_MS}
54
+ * — the host has to receive and store the upload before it can answer.
55
+ */
56
+ export declare const PRIVATE_STORAGE_PUT_TIMEOUT_MS = 120000;
57
+ /**
58
+ * `privateStorage.get` ALSO waits the longer timeout — downloading a large
59
+ * private file's bytes back through the host takes as long as uploading
60
+ * one, unlike `delete` / `list` / `getLink` which only move a little JSON.
61
+ */
62
+ export declare const PRIVATE_STORAGE_GET_TIMEOUT_MS = 120000;
63
+ /**
64
+ * Per-file size cap enforced client-side, before the request is even sent —
65
+ * matches the host's own `tooLarge` limit. Same numeric value as public
66
+ * storage's `MAX_PUBLIC_FILE_SIZE_BYTES` but a distinct constant: the two
67
+ * limits are independent and may diverge. See the README "Private storage"
68
+ * section for the full semantics (scopes, any content type, path rules,
69
+ * read/write permissions).
70
+ */
71
+ export declare const MAX_PRIVATE_FILE_SIZE_BYTES: number;
72
+ /**
73
+ * Lower bound for `put`'s `options.expiresIn` (seconds) — there is no upper
74
+ * bound beyond what fits in a safe integer, same as public storage. See
75
+ * {@link validatePrivateExpiresIn}.
76
+ */
77
+ export declare const MIN_PRIVATE_FILE_EXPIRES_IN_SECONDS = 1;
78
+ /**
79
+ * Upper bound for `getLink`'s `options.expiresIn` (seconds) — 7 days. A
80
+ * signed link is meant to be shared short-lived; unlike a file's own
81
+ * `expiresIn` (no maximum), a link's lifetime is capped. See
82
+ * {@link validateLinkExpiresIn}.
83
+ */
84
+ export declare const MAX_PRIVATE_LINK_EXPIRES_IN_SECONDS: number;
85
+ /**
86
+ * Default link lifetime (seconds) applied by the HOST when `getLink` is
87
+ * called with no `options.expiresIn` — the SDK never fills this in locally
88
+ * (an absent `expiresIn` on the wire genuinely means "use the server
89
+ * default"); documented here only so callers don't have to go dig it out of
90
+ * the README.
91
+ */
92
+ export declare const DEFAULT_PRIVATE_LINK_EXPIRES_IN_SECONDS = 3600;
93
+ /** Max length of a private storage `path`, in characters. See {@link validatePrivatePath}. */
94
+ export declare const MAX_PRIVATE_PATH_LENGTH = 256;
95
+ /** Max number of `/`-separated segments in a private storage `path`. See {@link validatePrivatePath}. */
96
+ export declare const MAX_PRIVATE_PATH_SEGMENTS = 8;
97
+ /**
98
+ * Validates a private storage `path` before any request is sent — the same
99
+ * rule the server enforces (`PublicStorage.validatePath`, generalized to
100
+ * both storage kinds): `/`-separated segments of letters, digits, `.`, `_`,
101
+ * `-`; at most {@link MAX_PRIVATE_PATH_SEGMENTS} segments; at most
102
+ * {@link MAX_PRIVATE_PATH_LENGTH} characters total; no segment may be empty
103
+ * or start with `.` (blocks `..` traversal and hidden-file-style names).
104
+ *
105
+ * This is a client-side fast-fail — the host/server validates the same rule
106
+ * independently and can still answer `error: 'invalidPath'` over the wire
107
+ * (e.g. a caller bypassing the SDK). Throws `PrivateStorageError('invalidPath')`
108
+ * on any violation.
109
+ */
110
+ export declare function validatePrivatePath(path: string): void;
111
+ /**
112
+ * Validates `PrivateStorageApi.put`'s optional `options.expiresIn` (seconds)
113
+ * before any request is sent. `undefined` is always valid — expiry is
114
+ * opt-in; omitting it keeps the file permanent. When set, it must be a
115
+ * positive safe integer (`Number.isSafeInteger`, `>= 1`) — no upper bound,
116
+ * same as public storage's file expiry. Throws
117
+ * `PrivateStorageError('invalidExpiry')` otherwise (e.g. `0`, negative,
118
+ * non-integer, `NaN`, `Infinity`, or above `Number.MAX_SAFE_INTEGER`).
119
+ */
120
+ export declare function validatePrivateExpiresIn(expiresIn: number | undefined): void;
121
+ /**
122
+ * Validates `getLink`'s optional `options.expiresIn` (seconds) before any
123
+ * request is sent. `undefined` is always valid — the host applies
124
+ * {@link DEFAULT_PRIVATE_LINK_EXPIRES_IN_SECONDS}. When set, it must be a
125
+ * positive safe integer AND at most
126
+ * {@link MAX_PRIVATE_LINK_EXPIRES_IN_SECONDS} (7 days) — unlike a file's own
127
+ * `expiresIn` (no maximum), a signed link's lifetime is capped. Throws
128
+ * `PrivateStorageError('invalidExpiry')` otherwise.
129
+ */
130
+ export declare function validateLinkExpiresIn(expiresIn: number | undefined): void;
131
+ /**
132
+ * Builds the `expiresIn` part of a `putPrivateFile` / `getPrivateFileLink`
133
+ * wire message from an options' `expiresIn`: an empty object when unset, so
134
+ * `expiresIn` is a genuinely absent key on the message when the caller
135
+ * didn't opt in — not a key present with value `undefined`. Spread into the
136
+ * message object, e.g.
137
+ * `{ type: 'putPrivateFile', ..., ...privateFileExpiryField(options?.expiresIn) }`.
138
+ * Call {@link validatePrivateExpiresIn} / {@link validateLinkExpiresIn}
139
+ * first — this does no validation of its own. Shared by both `put` and
140
+ * `getLink` since the field-presence rule is identical.
141
+ */
142
+ export declare function privateFileExpiryField(expiresIn: number | undefined): {
143
+ expiresIn: number;
144
+ } | Record<string, never>;
145
+ /**
146
+ * Options for `PrivateStorageApi.put`.
147
+ */
148
+ export type PrivateStoragePutOptions = {
149
+ /**
150
+ * Opt-in expiry, in seconds, as a positive safe integer — no upper bound.
151
+ * `get`/`getLink` 404 once expired and the server deletes the file. Omit
152
+ * for a permanent file (the default) — rewriting the same `path` later
153
+ * without `expiresIn` makes it permanent again. Validated locally with
154
+ * {@link validatePrivateExpiresIn}; an invalid value rejects with
155
+ * `PrivateStorageError('invalidExpiry')` before any request is sent.
156
+ */
157
+ expiresIn?: number;
158
+ };
159
+ /**
160
+ * Options for `PrivateStorageApi.getLink`.
161
+ */
162
+ export type PrivateStorageGetLinkOptions = {
163
+ /** Scope to resolve `path` in — `'app'` by default. */
164
+ scope?: PrivateStorageScope;
165
+ /**
166
+ * Link lifetime, in seconds, as a positive safe integer, capped at
167
+ * {@link MAX_PRIVATE_LINK_EXPIRES_IN_SECONDS} (7 days). Omit for the
168
+ * host's default ({@link DEFAULT_PRIVATE_LINK_EXPIRES_IN_SECONDS}, 1
169
+ * hour). The link also dies early if the file itself is deleted or
170
+ * expires first. Validated locally with {@link validateLinkExpiresIn};
171
+ * an invalid value rejects with `PrivateStorageError('invalidExpiry')`
172
+ * before any request is sent.
173
+ */
174
+ expiresIn?: number;
175
+ };
176
+ /**
177
+ * Private file storage an app can write to, scoped to the vitre's TEAM —
178
+ * see the README "Private storage" section for the full semantics. Unlike
179
+ * `publicStorage`, files here have NO public link: reading requires either
180
+ * the host round-trip (`get`) or a temporary signed link (`getLink`).
181
+ * Readable by any vitre or companion of the team; writable only by a
182
+ * Vitre-hosted app.
183
+ *
184
+ * Exposed as `connector.privateStorage` / `frame.privateStorage` (full —
185
+ * this type) and, read-only, as `companionConnector.privateStorage` /
186
+ * `companionFrame.privateStorage` (`list`/`get`/`getLink` only — see
187
+ * {@link PrivateStorageReadApi}).
188
+ */
189
+ export type PrivateStorageApi = {
190
+ /**
191
+ * Upload (or overwrite) a file at `path` within `scope` (`'app'` by
192
+ * default — this app's own space; `'shared'` is a space every app of the
193
+ * team shares). Any content type is accepted — nothing here is ever
194
+ * served publicly as-is. `data` may be an `ArrayBuffer`, `Blob`, or
195
+ * `Uint8Array`; it is normalized to an `ArrayBuffer` and transferred to
196
+ * the host zero-copy — don't reuse the buffer you pass after calling
197
+ * `put` (it is detached, same as any other `Transferable` handed to
198
+ * `postMessage`). Rejects locally with `PrivateStorageError('tooLarge')`,
199
+ * without a round-trip, if the payload exceeds
200
+ * {@link MAX_PRIVATE_FILE_SIZE_BYTES}. Rejects locally with
201
+ * `PrivateStorageError('invalidPath')` if `path` fails
202
+ * {@link validatePrivatePath}. Overwriting an existing path replaces the
203
+ * file; readers revalidate.
204
+ *
205
+ * `options.expiresIn` opts the file into automatic deletion — see
206
+ * {@link PrivateStoragePutOptions}. Invalid values reject locally with
207
+ * `PrivateStorageError('invalidExpiry')`, without a round-trip.
208
+ *
209
+ * Vitre-only — not exposed on `CompanionConnector` / a companion `Frame`.
210
+ */
211
+ put(path: string, data: ArrayBuffer | Blob | Uint8Array, contentType: string, scope?: PrivateStorageScope, options?: PrivateStoragePutOptions): Promise<PrivateFile>;
212
+ /**
213
+ * Delete the file at `path` within `scope` (`'app'` by default). Resolves
214
+ * even if the path didn't exist. Vitre-only — not exposed on
215
+ * `CompanionConnector` / a companion `Frame`.
216
+ */
217
+ delete(path: string, scope?: PrivateStorageScope): Promise<void>;
218
+ /**
219
+ * List files within `scope` (`'app'` by default), optionally filtered to
220
+ * those whose path starts with `prefix`. Expired files are omitted.
221
+ */
222
+ list(prefix?: string, scope?: PrivateStorageScope): Promise<PrivateStorageListResult>;
223
+ /**
224
+ * Download the bytes of the file at `path` within `scope` (`'app'` by
225
+ * default). Rejects with `PrivateStorageError('notFound')` if the path
226
+ * doesn't exist or has expired.
227
+ */
228
+ get(path: string, scope?: PrivateStorageScope): Promise<{
229
+ data: ArrayBuffer;
230
+ contentType: string;
231
+ }>;
232
+ /**
233
+ * Mint a temporary signed link to the file at `path` within
234
+ * `options.scope` (`'app'` by default) — readable without authentication
235
+ * until `link.expiresAt`, or until the file itself is deleted/expires,
236
+ * whichever comes first. See {@link PrivateStorageGetLinkOptions}.
237
+ * Rejects with `PrivateStorageError('notFound')` if the path doesn't
238
+ * exist or has expired.
239
+ */
240
+ getLink(path: string, options?: PrivateStorageGetLinkOptions): Promise<PrivateFileLink>;
241
+ };
242
+ /**
243
+ * Read-only subset of {@link PrivateStorageApi} exposed on
244
+ * `CompanionConnector` / a companion `Frame` — writes stay vitre-only, so
245
+ * `put`/`delete` are intentionally absent at the type level (the companion
246
+ * host answers them with `error: 'unsupported'` anyway, same as an old
247
+ * vitre host that predates the feature).
248
+ */
249
+ export type PrivateStorageReadApi = Pick<PrivateStorageApi, 'list' | 'get' | 'getLink'>;
@@ -0,0 +1,158 @@
1
+ /**
2
+ * Thrown by `privateStorage.put` / `.delete` / `.list` / `.get` / `.getLink`
3
+ * when the host answers with `ok: false`, when the request times out, or
4
+ * locally (without a round-trip) when the payload exceeds
5
+ * {@link MAX_PRIVATE_FILE_SIZE_BYTES}, the `path` fails
6
+ * {@link validatePrivatePath}, or an `expiresIn` fails validation — see
7
+ * {@link PrivateStorageErrorCode}.
8
+ */
9
+ export class PrivateStorageError extends Error {
10
+ constructor(code) {
11
+ super(`Private storage request failed: ${code}`);
12
+ // Not a TS constructor parameter property — those aren't erasable syntax,
13
+ // so Node's type-stripping test runner (`pnpm test`, no transpile step)
14
+ // fails to load this module. Plain field + explicit assignment instead;
15
+ // identical runtime shape (still a public readonly `code`), same pattern
16
+ // as `PublicStorageError`.
17
+ Object.defineProperty(this, "code", {
18
+ enumerable: true,
19
+ configurable: true,
20
+ writable: true,
21
+ value: void 0
22
+ });
23
+ this.name = 'PrivateStorageError';
24
+ this.code = code;
25
+ }
26
+ }
27
+ /**
28
+ * How long `privateStorage.delete` / `.list` / `.getLink` wait for
29
+ * `privateStorageResponse` before treating the host as not supporting the
30
+ * private storage API. Passed as `Connector`/`Frame`/`CompanionConnector`'s
31
+ * private `postRequest(..., timeout)` 4th argument, which removes the
32
+ * pending resolver when the timer fires (same fix as
33
+ * {@link PUBLIC_STORAGE_TIMEOUT_MS} in `PublicStorage.ts` — see its doc
34
+ * comment).
35
+ */
36
+ export const PRIVATE_STORAGE_TIMEOUT_MS = 10000;
37
+ /**
38
+ * `privateStorage.put` waits longer than {@link PRIVATE_STORAGE_TIMEOUT_MS}
39
+ * — the host has to receive and store the upload before it can answer.
40
+ */
41
+ export const PRIVATE_STORAGE_PUT_TIMEOUT_MS = 120000;
42
+ /**
43
+ * `privateStorage.get` ALSO waits the longer timeout — downloading a large
44
+ * private file's bytes back through the host takes as long as uploading
45
+ * one, unlike `delete` / `list` / `getLink` which only move a little JSON.
46
+ */
47
+ export const PRIVATE_STORAGE_GET_TIMEOUT_MS = 120000;
48
+ /**
49
+ * Per-file size cap enforced client-side, before the request is even sent —
50
+ * matches the host's own `tooLarge` limit. Same numeric value as public
51
+ * storage's `MAX_PUBLIC_FILE_SIZE_BYTES` but a distinct constant: the two
52
+ * limits are independent and may diverge. See the README "Private storage"
53
+ * section for the full semantics (scopes, any content type, path rules,
54
+ * read/write permissions).
55
+ */
56
+ export const MAX_PRIVATE_FILE_SIZE_BYTES = 50 * 1024 * 1024;
57
+ /**
58
+ * Lower bound for `put`'s `options.expiresIn` (seconds) — there is no upper
59
+ * bound beyond what fits in a safe integer, same as public storage. See
60
+ * {@link validatePrivateExpiresIn}.
61
+ */
62
+ export const MIN_PRIVATE_FILE_EXPIRES_IN_SECONDS = 1;
63
+ /**
64
+ * Upper bound for `getLink`'s `options.expiresIn` (seconds) — 7 days. A
65
+ * signed link is meant to be shared short-lived; unlike a file's own
66
+ * `expiresIn` (no maximum), a link's lifetime is capped. See
67
+ * {@link validateLinkExpiresIn}.
68
+ */
69
+ export const MAX_PRIVATE_LINK_EXPIRES_IN_SECONDS = 7 * 24 * 60 * 60;
70
+ /**
71
+ * Default link lifetime (seconds) applied by the HOST when `getLink` is
72
+ * called with no `options.expiresIn` — the SDK never fills this in locally
73
+ * (an absent `expiresIn` on the wire genuinely means "use the server
74
+ * default"); documented here only so callers don't have to go dig it out of
75
+ * the README.
76
+ */
77
+ export const DEFAULT_PRIVATE_LINK_EXPIRES_IN_SECONDS = 3600;
78
+ /** Max length of a private storage `path`, in characters. See {@link validatePrivatePath}. */
79
+ export const MAX_PRIVATE_PATH_LENGTH = 256;
80
+ /** Max number of `/`-separated segments in a private storage `path`. See {@link validatePrivatePath}. */
81
+ export const MAX_PRIVATE_PATH_SEGMENTS = 8;
82
+ const PRIVATE_PATH_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
83
+ /**
84
+ * Validates a private storage `path` before any request is sent — the same
85
+ * rule the server enforces (`PublicStorage.validatePath`, generalized to
86
+ * both storage kinds): `/`-separated segments of letters, digits, `.`, `_`,
87
+ * `-`; at most {@link MAX_PRIVATE_PATH_SEGMENTS} segments; at most
88
+ * {@link MAX_PRIVATE_PATH_LENGTH} characters total; no segment may be empty
89
+ * or start with `.` (blocks `..` traversal and hidden-file-style names).
90
+ *
91
+ * This is a client-side fast-fail — the host/server validates the same rule
92
+ * independently and can still answer `error: 'invalidPath'` over the wire
93
+ * (e.g. a caller bypassing the SDK). Throws `PrivateStorageError('invalidPath')`
94
+ * on any violation.
95
+ */
96
+ export function validatePrivatePath(path) {
97
+ if (typeof path !== 'string' || path.length === 0 || path.length > MAX_PRIVATE_PATH_LENGTH) {
98
+ throw new PrivateStorageError('invalidPath');
99
+ }
100
+ const segments = path.split('/');
101
+ if (segments.length > MAX_PRIVATE_PATH_SEGMENTS) {
102
+ throw new PrivateStorageError('invalidPath');
103
+ }
104
+ for (const segment of segments) {
105
+ if (segment.length === 0 || segment.startsWith('.') || !PRIVATE_PATH_SEGMENT_PATTERN.test(segment)) {
106
+ throw new PrivateStorageError('invalidPath');
107
+ }
108
+ }
109
+ }
110
+ /**
111
+ * Validates `PrivateStorageApi.put`'s optional `options.expiresIn` (seconds)
112
+ * before any request is sent. `undefined` is always valid — expiry is
113
+ * opt-in; omitting it keeps the file permanent. When set, it must be a
114
+ * positive safe integer (`Number.isSafeInteger`, `>= 1`) — no upper bound,
115
+ * same as public storage's file expiry. Throws
116
+ * `PrivateStorageError('invalidExpiry')` otherwise (e.g. `0`, negative,
117
+ * non-integer, `NaN`, `Infinity`, or above `Number.MAX_SAFE_INTEGER`).
118
+ */
119
+ export function validatePrivateExpiresIn(expiresIn) {
120
+ if (expiresIn === undefined)
121
+ return;
122
+ if (!Number.isSafeInteger(expiresIn) || expiresIn < MIN_PRIVATE_FILE_EXPIRES_IN_SECONDS) {
123
+ throw new PrivateStorageError('invalidExpiry');
124
+ }
125
+ }
126
+ /**
127
+ * Validates `getLink`'s optional `options.expiresIn` (seconds) before any
128
+ * request is sent. `undefined` is always valid — the host applies
129
+ * {@link DEFAULT_PRIVATE_LINK_EXPIRES_IN_SECONDS}. When set, it must be a
130
+ * positive safe integer AND at most
131
+ * {@link MAX_PRIVATE_LINK_EXPIRES_IN_SECONDS} (7 days) — unlike a file's own
132
+ * `expiresIn` (no maximum), a signed link's lifetime is capped. Throws
133
+ * `PrivateStorageError('invalidExpiry')` otherwise.
134
+ */
135
+ export function validateLinkExpiresIn(expiresIn) {
136
+ if (expiresIn === undefined)
137
+ return;
138
+ if (!Number.isSafeInteger(expiresIn) ||
139
+ expiresIn < MIN_PRIVATE_FILE_EXPIRES_IN_SECONDS ||
140
+ expiresIn > MAX_PRIVATE_LINK_EXPIRES_IN_SECONDS) {
141
+ throw new PrivateStorageError('invalidExpiry');
142
+ }
143
+ }
144
+ /**
145
+ * Builds the `expiresIn` part of a `putPrivateFile` / `getPrivateFileLink`
146
+ * wire message from an options' `expiresIn`: an empty object when unset, so
147
+ * `expiresIn` is a genuinely absent key on the message when the caller
148
+ * didn't opt in — not a key present with value `undefined`. Spread into the
149
+ * message object, e.g.
150
+ * `{ type: 'putPrivateFile', ..., ...privateFileExpiryField(options?.expiresIn) }`.
151
+ * Call {@link validatePrivateExpiresIn} / {@link validateLinkExpiresIn}
152
+ * first — this does no validation of its own. Shared by both `put` and
153
+ * `getLink` since the field-presence rule is identical.
154
+ */
155
+ export function privateFileExpiryField(expiresIn) {
156
+ return expiresIn === undefined ? {} : { expiresIn };
157
+ }
158
+ //# sourceMappingURL=PrivateStorage.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"PrivateStorage.js","sourceRoot":"","sources":["../../Common/PrivateStorage.ts"],"names":[],"mappings":"AAuCA;;;;;;;GAOG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAO5C,YAAY,IAA6B;QACvC,KAAK,CAAC,mCAAmC,IAAI,EAAE,CAAC,CAAA;QAPlD,0EAA0E;QAC1E,wEAAwE;QACxE,wEAAwE;QACxE,yEAAyE;QACzE,2BAA2B;QACX;;;;;WAA6B;QAG3C,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAK,CAAA;AAE/C;;;GAGG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,MAAM,CAAA;AAEpD;;;;GAIG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,MAAM,CAAA;AAEpD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAA;AAE3D;;;;GAIG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,CAAC,CAAA;AAEpD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAA;AAEnE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uCAAuC,GAAG,IAAI,CAAA;AAE3D,8FAA8F;AAC9F,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAA;AAE1C,yGAAyG;AACzG,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAA;AAE1C,MAAM,4BAA4B,GAAG,mBAAmB,CAAA;AAExD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,uBAAuB,EAAE,CAAC;QAC3F,MAAM,IAAI,mBAAmB,CAAC,aAAa,CAAC,CAAA;IAC9C,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAChC,IAAI,QAAQ,CAAC,MAAM,GAAG,yBAAyB,EAAE,CAAC;QAChD,MAAM,IAAI,mBAAmB,CAAC,aAAa,CAAC,CAAA;IAC9C,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,4BAA4B,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACnG,MAAM,IAAI,mBAAmB,CAAC,aAAa,CAAC,CAAA;QAC9C,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,SAA6B;IACpE,IAAI,SAAS,KAAK,SAAS;QAAE,OAAM;IACnC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,mCAAmC,EAAE,CAAC;QACxF,MAAM,IAAI,mBAAmB,CAAC,eAAe,CAAC,CAAA;IAChD,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,SAA6B;IACjE,IAAI,SAAS,KAAK,SAAS;QAAE,OAAM;IACnC,IACE,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC;QAChC,SAAS,GAAG,mCAAmC;QAC/C,SAAS,GAAG,mCAAmC,EAC/C,CAAC;QACD,MAAM,IAAI,mBAAmB,CAAC,eAAe,CAAC,CAAA;IAChD,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CACpC,SAA6B;IAE7B,OAAO,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAA;AACrD,CAAC","sourcesContent":["import type { PrivateFile, PrivateFileLink, PrivateStorageListResult, PrivateStorageScope } from './Common.Model.js'\n\n/**\n * Error codes for the private storage API (`Connector.privateStorage` /\n * `Frame.privateStorage` / `CompanionConnector.privateStorage` /\n * `CompanionFrame.privateStorage`).\n *\n * The six wire codes — `tooLarge`, `invalidPath`, `storageNotConfigured`,\n * `notFound`, `unavailable`, `failed` — come straight from the host's\n * `privateStorageResponse.error`. `unsupported` and `invalidExpiry` are\n * synthesized locally by the SDK, never sent by the host:\n * - `unsupported` fires when no response arrives within the request's\n * timeout (see {@link PRIVATE_STORAGE_TIMEOUT_MS} /\n * {@link PRIVATE_STORAGE_PUT_TIMEOUT_MS} /\n * {@link PRIVATE_STORAGE_GET_TIMEOUT_MS}) — the signature of a host that\n * predates this feature, which silently ignores the unknown\n * `putPrivateFile` / `deletePrivateFile` / `listPrivateFiles` /\n * `getPrivateFile` / `getPrivateFileLink` message types instead of\n * answering. A companion host that KNOWS about private storage but\n * doesn't support writes answers `putPrivateFile` / `deletePrivateFile`\n * with this same code over the wire instead (see\n * `CompanionConnector`/`CompanionFrame`, which don't even expose\n * `put`/`delete` at the type level).\n * - `invalidExpiry` fires when `put`'s `options.expiresIn`, or `getLink`'s\n * `options.expiresIn`, isn't a positive safe integer — or, for `getLink`,\n * exceeds {@link MAX_PRIVATE_LINK_EXPIRES_IN_SECONDS} — see\n * {@link validatePrivateExpiresIn} / {@link validateLinkExpiresIn}.\n * Rejected before any request is sent.\n */\nexport type PrivateStorageErrorCode =\n | 'tooLarge'\n | 'invalidPath'\n | 'invalidExpiry'\n | 'storageNotConfigured'\n | 'notFound'\n | 'unsupported'\n | 'unavailable'\n | 'failed'\n\n/**\n * Thrown by `privateStorage.put` / `.delete` / `.list` / `.get` / `.getLink`\n * when the host answers with `ok: false`, when the request times out, or\n * locally (without a round-trip) when the payload exceeds\n * {@link MAX_PRIVATE_FILE_SIZE_BYTES}, the `path` fails\n * {@link validatePrivatePath}, or an `expiresIn` fails validation — see\n * {@link PrivateStorageErrorCode}.\n */\nexport class PrivateStorageError extends Error {\n // Not a TS constructor parameter property — those aren't erasable syntax,\n // so Node's type-stripping test runner (`pnpm test`, no transpile step)\n // fails to load this module. Plain field + explicit assignment instead;\n // identical runtime shape (still a public readonly `code`), same pattern\n // as `PublicStorageError`.\n public readonly code: PrivateStorageErrorCode\n constructor(code: PrivateStorageErrorCode) {\n super(`Private storage request failed: ${code}`)\n this.name = 'PrivateStorageError'\n this.code = code\n }\n}\n\n/**\n * How long `privateStorage.delete` / `.list` / `.getLink` wait for\n * `privateStorageResponse` before treating the host as not supporting the\n * private storage API. Passed as `Connector`/`Frame`/`CompanionConnector`'s\n * private `postRequest(..., timeout)` 4th argument, which removes the\n * pending resolver when the timer fires (same fix as\n * {@link PUBLIC_STORAGE_TIMEOUT_MS} in `PublicStorage.ts` — see its doc\n * comment).\n */\nexport const PRIVATE_STORAGE_TIMEOUT_MS = 10000\n\n/**\n * `privateStorage.put` waits longer than {@link PRIVATE_STORAGE_TIMEOUT_MS}\n * — the host has to receive and store the upload before it can answer.\n */\nexport const PRIVATE_STORAGE_PUT_TIMEOUT_MS = 120000\n\n/**\n * `privateStorage.get` ALSO waits the longer timeout — downloading a large\n * private file's bytes back through the host takes as long as uploading\n * one, unlike `delete` / `list` / `getLink` which only move a little JSON.\n */\nexport const PRIVATE_STORAGE_GET_TIMEOUT_MS = 120000\n\n/**\n * Per-file size cap enforced client-side, before the request is even sent —\n * matches the host's own `tooLarge` limit. Same numeric value as public\n * storage's `MAX_PUBLIC_FILE_SIZE_BYTES` but a distinct constant: the two\n * limits are independent and may diverge. See the README \"Private storage\"\n * section for the full semantics (scopes, any content type, path rules,\n * read/write permissions).\n */\nexport const MAX_PRIVATE_FILE_SIZE_BYTES = 50 * 1024 * 1024\n\n/**\n * Lower bound for `put`'s `options.expiresIn` (seconds) — there is no upper\n * bound beyond what fits in a safe integer, same as public storage. See\n * {@link validatePrivateExpiresIn}.\n */\nexport const MIN_PRIVATE_FILE_EXPIRES_IN_SECONDS = 1\n\n/**\n * Upper bound for `getLink`'s `options.expiresIn` (seconds) — 7 days. A\n * signed link is meant to be shared short-lived; unlike a file's own\n * `expiresIn` (no maximum), a link's lifetime is capped. See\n * {@link validateLinkExpiresIn}.\n */\nexport const MAX_PRIVATE_LINK_EXPIRES_IN_SECONDS = 7 * 24 * 60 * 60\n\n/**\n * Default link lifetime (seconds) applied by the HOST when `getLink` is\n * called with no `options.expiresIn` — the SDK never fills this in locally\n * (an absent `expiresIn` on the wire genuinely means \"use the server\n * default\"); documented here only so callers don't have to go dig it out of\n * the README.\n */\nexport const DEFAULT_PRIVATE_LINK_EXPIRES_IN_SECONDS = 3600\n\n/** Max length of a private storage `path`, in characters. See {@link validatePrivatePath}. */\nexport const MAX_PRIVATE_PATH_LENGTH = 256\n\n/** Max number of `/`-separated segments in a private storage `path`. See {@link validatePrivatePath}. */\nexport const MAX_PRIVATE_PATH_SEGMENTS = 8\n\nconst PRIVATE_PATH_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/\n\n/**\n * Validates a private storage `path` before any request is sent — the same\n * rule the server enforces (`PublicStorage.validatePath`, generalized to\n * both storage kinds): `/`-separated segments of letters, digits, `.`, `_`,\n * `-`; at most {@link MAX_PRIVATE_PATH_SEGMENTS} segments; at most\n * {@link MAX_PRIVATE_PATH_LENGTH} characters total; no segment may be empty\n * or start with `.` (blocks `..` traversal and hidden-file-style names).\n *\n * This is a client-side fast-fail — the host/server validates the same rule\n * independently and can still answer `error: 'invalidPath'` over the wire\n * (e.g. a caller bypassing the SDK). Throws `PrivateStorageError('invalidPath')`\n * on any violation.\n */\nexport function validatePrivatePath(path: string): void {\n if (typeof path !== 'string' || path.length === 0 || path.length > MAX_PRIVATE_PATH_LENGTH) {\n throw new PrivateStorageError('invalidPath')\n }\n const segments = path.split('/')\n if (segments.length > MAX_PRIVATE_PATH_SEGMENTS) {\n throw new PrivateStorageError('invalidPath')\n }\n for (const segment of segments) {\n if (segment.length === 0 || segment.startsWith('.') || !PRIVATE_PATH_SEGMENT_PATTERN.test(segment)) {\n throw new PrivateStorageError('invalidPath')\n }\n }\n}\n\n/**\n * Validates `PrivateStorageApi.put`'s optional `options.expiresIn` (seconds)\n * before any request is sent. `undefined` is always valid — expiry is\n * opt-in; omitting it keeps the file permanent. When set, it must be a\n * positive safe integer (`Number.isSafeInteger`, `>= 1`) — no upper bound,\n * same as public storage's file expiry. Throws\n * `PrivateStorageError('invalidExpiry')` otherwise (e.g. `0`, negative,\n * non-integer, `NaN`, `Infinity`, or above `Number.MAX_SAFE_INTEGER`).\n */\nexport function validatePrivateExpiresIn(expiresIn: number | undefined): void {\n if (expiresIn === undefined) return\n if (!Number.isSafeInteger(expiresIn) || expiresIn < MIN_PRIVATE_FILE_EXPIRES_IN_SECONDS) {\n throw new PrivateStorageError('invalidExpiry')\n }\n}\n\n/**\n * Validates `getLink`'s optional `options.expiresIn` (seconds) before any\n * request is sent. `undefined` is always valid — the host applies\n * {@link DEFAULT_PRIVATE_LINK_EXPIRES_IN_SECONDS}. When set, it must be a\n * positive safe integer AND at most\n * {@link MAX_PRIVATE_LINK_EXPIRES_IN_SECONDS} (7 days) — unlike a file's own\n * `expiresIn` (no maximum), a signed link's lifetime is capped. Throws\n * `PrivateStorageError('invalidExpiry')` otherwise.\n */\nexport function validateLinkExpiresIn(expiresIn: number | undefined): void {\n if (expiresIn === undefined) return\n if (\n !Number.isSafeInteger(expiresIn) ||\n expiresIn < MIN_PRIVATE_FILE_EXPIRES_IN_SECONDS ||\n expiresIn > MAX_PRIVATE_LINK_EXPIRES_IN_SECONDS\n ) {\n throw new PrivateStorageError('invalidExpiry')\n }\n}\n\n/**\n * Builds the `expiresIn` part of a `putPrivateFile` / `getPrivateFileLink`\n * wire message from an options' `expiresIn`: an empty object when unset, so\n * `expiresIn` is a genuinely absent key on the message when the caller\n * didn't opt in — not a key present with value `undefined`. Spread into the\n * message object, e.g.\n * `{ type: 'putPrivateFile', ..., ...privateFileExpiryField(options?.expiresIn) }`.\n * Call {@link validatePrivateExpiresIn} / {@link validateLinkExpiresIn}\n * first — this does no validation of its own. Shared by both `put` and\n * `getLink` since the field-presence rule is identical.\n */\nexport function privateFileExpiryField(\n expiresIn: number | undefined,\n): { expiresIn: number } | Record<string, never> {\n return expiresIn === undefined ? {} : { expiresIn }\n}\n\n/**\n * Options for `PrivateStorageApi.put`.\n */\nexport type PrivateStoragePutOptions = {\n /**\n * Opt-in expiry, in seconds, as a positive safe integer — no upper bound.\n * `get`/`getLink` 404 once expired and the server deletes the file. Omit\n * for a permanent file (the default) — rewriting the same `path` later\n * without `expiresIn` makes it permanent again. Validated locally with\n * {@link validatePrivateExpiresIn}; an invalid value rejects with\n * `PrivateStorageError('invalidExpiry')` before any request is sent.\n */\n expiresIn?: number\n}\n\n/**\n * Options for `PrivateStorageApi.getLink`.\n */\nexport type PrivateStorageGetLinkOptions = {\n /** Scope to resolve `path` in — `'app'` by default. */\n scope?: PrivateStorageScope\n /**\n * Link lifetime, in seconds, as a positive safe integer, capped at\n * {@link MAX_PRIVATE_LINK_EXPIRES_IN_SECONDS} (7 days). Omit for the\n * host's default ({@link DEFAULT_PRIVATE_LINK_EXPIRES_IN_SECONDS}, 1\n * hour). The link also dies early if the file itself is deleted or\n * expires first. Validated locally with {@link validateLinkExpiresIn};\n * an invalid value rejects with `PrivateStorageError('invalidExpiry')`\n * before any request is sent.\n */\n expiresIn?: number\n}\n\n/**\n * Private file storage an app can write to, scoped to the vitre's TEAM —\n * see the README \"Private storage\" section for the full semantics. Unlike\n * `publicStorage`, files here have NO public link: reading requires either\n * the host round-trip (`get`) or a temporary signed link (`getLink`).\n * Readable by any vitre or companion of the team; writable only by a\n * Vitre-hosted app.\n *\n * Exposed as `connector.privateStorage` / `frame.privateStorage` (full —\n * this type) and, read-only, as `companionConnector.privateStorage` /\n * `companionFrame.privateStorage` (`list`/`get`/`getLink` only — see\n * {@link PrivateStorageReadApi}).\n */\nexport type PrivateStorageApi = {\n /**\n * Upload (or overwrite) a file at `path` within `scope` (`'app'` by\n * default — this app's own space; `'shared'` is a space every app of the\n * team shares). Any content type is accepted — nothing here is ever\n * served publicly as-is. `data` may be an `ArrayBuffer`, `Blob`, or\n * `Uint8Array`; it is normalized to an `ArrayBuffer` and transferred to\n * the host zero-copy — don't reuse the buffer you pass after calling\n * `put` (it is detached, same as any other `Transferable` handed to\n * `postMessage`). Rejects locally with `PrivateStorageError('tooLarge')`,\n * without a round-trip, if the payload exceeds\n * {@link MAX_PRIVATE_FILE_SIZE_BYTES}. Rejects locally with\n * `PrivateStorageError('invalidPath')` if `path` fails\n * {@link validatePrivatePath}. Overwriting an existing path replaces the\n * file; readers revalidate.\n *\n * `options.expiresIn` opts the file into automatic deletion — see\n * {@link PrivateStoragePutOptions}. Invalid values reject locally with\n * `PrivateStorageError('invalidExpiry')`, without a round-trip.\n *\n * Vitre-only — not exposed on `CompanionConnector` / a companion `Frame`.\n */\n put(\n path: string,\n data: ArrayBuffer | Blob | Uint8Array,\n contentType: string,\n scope?: PrivateStorageScope,\n options?: PrivateStoragePutOptions,\n ): Promise<PrivateFile>\n /**\n * Delete the file at `path` within `scope` (`'app'` by default). Resolves\n * even if the path didn't exist. Vitre-only — not exposed on\n * `CompanionConnector` / a companion `Frame`.\n */\n delete(path: string, scope?: PrivateStorageScope): Promise<void>\n /**\n * List files within `scope` (`'app'` by default), optionally filtered to\n * those whose path starts with `prefix`. Expired files are omitted.\n */\n list(prefix?: string, scope?: PrivateStorageScope): Promise<PrivateStorageListResult>\n /**\n * Download the bytes of the file at `path` within `scope` (`'app'` by\n * default). Rejects with `PrivateStorageError('notFound')` if the path\n * doesn't exist or has expired.\n */\n get(path: string, scope?: PrivateStorageScope): Promise<{ data: ArrayBuffer; contentType: string }>\n /**\n * Mint a temporary signed link to the file at `path` within\n * `options.scope` (`'app'` by default) — readable without authentication\n * until `link.expiresAt`, or until the file itself is deleted/expires,\n * whichever comes first. See {@link PrivateStorageGetLinkOptions}.\n * Rejects with `PrivateStorageError('notFound')` if the path doesn't\n * exist or has expired.\n */\n getLink(path: string, options?: PrivateStorageGetLinkOptions): Promise<PrivateFileLink>\n}\n\n/**\n * Read-only subset of {@link PrivateStorageApi} exposed on\n * `CompanionConnector` / a companion `Frame` — writes stay vitre-only, so\n * `put`/`delete` are intentionally absent at the type level (the companion\n * host answers them with `error: 'unsupported'` anyway, same as an old\n * vitre host that predates the feature).\n */\nexport type PrivateStorageReadApi = Pick<PrivateStorageApi, 'list' | 'get' | 'getLink'>\n"]}
@@ -4,6 +4,7 @@ export { CrdtChannel, MIN_CRDT_HOST_VERSION, type CrdtAttachment, type CrdtInbou
4
4
  export { BlobStore } from './BlobStore.js';
5
5
  export { AppSettingsError, APP_SETTINGS_TIMEOUT_MS, type AppSettingsErrorCode, } from './AppSettings.js';
6
6
  export { PublicStorageError, PUBLIC_STORAGE_TIMEOUT_MS, PUBLIC_STORAGE_PUT_TIMEOUT_MS, MAX_PUBLIC_FILE_SIZE_BYTES, MIN_PUBLIC_FILE_EXPIRES_IN_SECONDS, validateExpiresIn, putPublicFileExpiryField, withDownloadUrlFallback, type PublicStorageErrorCode, type PublicStorageApi, type PublicStoragePutOptions, } from './PublicStorage.js';
7
+ export { PrivateStorageError, PRIVATE_STORAGE_TIMEOUT_MS, PRIVATE_STORAGE_PUT_TIMEOUT_MS, PRIVATE_STORAGE_GET_TIMEOUT_MS, MAX_PRIVATE_FILE_SIZE_BYTES, MIN_PRIVATE_FILE_EXPIRES_IN_SECONDS, MAX_PRIVATE_LINK_EXPIRES_IN_SECONDS, DEFAULT_PRIVATE_LINK_EXPIRES_IN_SECONDS, MAX_PRIVATE_PATH_LENGTH, MAX_PRIVATE_PATH_SEGMENTS, validatePrivatePath, validatePrivateExpiresIn, validateLinkExpiresIn, privateFileExpiryField, type PrivateStorageErrorCode, type PrivateStorageApi, type PrivateStorageReadApi, type PrivateStoragePutOptions, type PrivateStorageGetLinkOptions, } from './PrivateStorage.js';
7
8
  export { AiChannel, MIN_AI_HOST_VERSION, type AiTool, type AiToolHandler, type AiInboundMessage, type AiOutboundMessage, type AiPostMessage, } from './AiChannel.js';
8
9
  export declare const ensureDefaultValue: <T>(value: Partial<T> | null, defaultValue: T) => T;
9
10
  export * from './PreviewScaling.js';
@@ -4,6 +4,7 @@ export { CrdtChannel, MIN_CRDT_HOST_VERSION, } from './CrdtChannel.js';
4
4
  export { BlobStore } from './BlobStore.js';
5
5
  export { AppSettingsError, APP_SETTINGS_TIMEOUT_MS, } from './AppSettings.js';
6
6
  export { PublicStorageError, PUBLIC_STORAGE_TIMEOUT_MS, PUBLIC_STORAGE_PUT_TIMEOUT_MS, MAX_PUBLIC_FILE_SIZE_BYTES, MIN_PUBLIC_FILE_EXPIRES_IN_SECONDS, validateExpiresIn, putPublicFileExpiryField, withDownloadUrlFallback, } from './PublicStorage.js';
7
+ export { PrivateStorageError, PRIVATE_STORAGE_TIMEOUT_MS, PRIVATE_STORAGE_PUT_TIMEOUT_MS, PRIVATE_STORAGE_GET_TIMEOUT_MS, MAX_PRIVATE_FILE_SIZE_BYTES, MIN_PRIVATE_FILE_EXPIRES_IN_SECONDS, MAX_PRIVATE_LINK_EXPIRES_IN_SECONDS, DEFAULT_PRIVATE_LINK_EXPIRES_IN_SECONDS, MAX_PRIVATE_PATH_LENGTH, MAX_PRIVATE_PATH_SEGMENTS, validatePrivatePath, validatePrivateExpiresIn, validateLinkExpiresIn, privateFileExpiryField, } from './PrivateStorage.js';
7
8
  export { AiChannel, MIN_AI_HOST_VERSION, } from './AiChannel.js';
8
9
  export const ensureDefaultValue = (value, defaultValue) => {
9
10
  const ensureValue = (value, defaultValue) => {
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../Common/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,EACL,WAAW,EACX,qBAAqB,GAKtB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EACL,gBAAgB,EAChB,uBAAuB,GAExB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,6BAA6B,EAC7B,0BAA0B,EAC1B,kCAAkC,EAClC,iBAAiB,EACjB,wBAAwB,EACxB,uBAAuB,GAIxB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,SAAS,EACT,mBAAmB,GAMpB,MAAM,gBAAgB,CAAA;AAEvB,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,KAAwB,EACxB,YAAe,EACf,EAAE;IACF,MAAM,WAAW,GAAG,CAAC,KAAU,EAAE,YAAiB,EAAE,EAAE;QACpD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAC/B,OAAO,KAAK,CAAA;QACd,CAAC;QAED,IAAI,OAAO,KAAK,KAAK,OAAO,YAAY,EAAE,CAAC;YACzC,OAAO,YAAY,CAAA;QACrB,CAAC;QAED,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;YACrC,IAAI,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;gBAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC1B,OAAO,YAAY,CAAA;gBACrB,CAAC;qBAAM,CAAC;oBACN,OAAO,KAAK,CAAA;gBACd,CAAC;YACH,CAAC;YAED,KAAK,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAA;YACzD,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;gBACxC,KAAK,CAAC,GAAG,CAAC,GAAG,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAA;YAChE,CAAC,CAAC,CAAA;QACJ,CAAC;QAED,OAAO,KAAK,CAAA;IACd,CAAC,CAAA;IAED,OAAO,WAAW,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,YAAY,CAAM,CAAA;AACzE,CAAC,CAAA;AACD,cAAc,qBAAqB,CAAA","sourcesContent":["export * from './Common.Model.js'\nexport { compareVersions, isMinVersion } from './Version.js'\nexport {\n CrdtChannel,\n MIN_CRDT_HOST_VERSION,\n type CrdtAttachment,\n type CrdtInboundMessage,\n type CrdtOutboundMessage,\n type CrdtPostMessage,\n} from './CrdtChannel.js'\nexport { BlobStore } from './BlobStore.js'\nexport {\n AppSettingsError,\n APP_SETTINGS_TIMEOUT_MS,\n type AppSettingsErrorCode,\n} from './AppSettings.js'\nexport {\n PublicStorageError,\n PUBLIC_STORAGE_TIMEOUT_MS,\n PUBLIC_STORAGE_PUT_TIMEOUT_MS,\n MAX_PUBLIC_FILE_SIZE_BYTES,\n MIN_PUBLIC_FILE_EXPIRES_IN_SECONDS,\n validateExpiresIn,\n putPublicFileExpiryField,\n withDownloadUrlFallback,\n type PublicStorageErrorCode,\n type PublicStorageApi,\n type PublicStoragePutOptions,\n} from './PublicStorage.js'\nexport {\n AiChannel,\n MIN_AI_HOST_VERSION,\n type AiTool,\n type AiToolHandler,\n type AiInboundMessage,\n type AiOutboundMessage,\n type AiPostMessage,\n} from './AiChannel.js'\n\nexport const ensureDefaultValue = <T>(\n value: Partial<T> | null,\n defaultValue: T,\n) => {\n const ensureValue = (value: any, defaultValue: any) => {\n if (defaultValue === undefined) {\n return value\n }\n\n if (typeof value !== typeof defaultValue) {\n return defaultValue\n }\n\n if (typeof defaultValue === 'object') {\n if (Array.isArray(defaultValue)) {\n if (!Array.isArray(value)) {\n return defaultValue\n } else {\n return value\n }\n }\n\n value = value === undefined || value == null ? {} : value\n Object.keys(defaultValue).forEach((key) => {\n value[key] = ensureDefaultValue(value[key], defaultValue[key])\n })\n }\n\n return value\n }\n\n return ensureValue(value === undefined ? {} : value, defaultValue) as T\n}\nexport * from './PreviewScaling.js'\n"]}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../Common/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,EACL,WAAW,EACX,qBAAqB,GAKtB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EACL,gBAAgB,EAChB,uBAAuB,GAExB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,6BAA6B,EAC7B,0BAA0B,EAC1B,kCAAkC,EAClC,iBAAiB,EACjB,wBAAwB,EACxB,uBAAuB,GAIxB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,8BAA8B,EAC9B,8BAA8B,EAC9B,2BAA2B,EAC3B,mCAAmC,EACnC,mCAAmC,EACnC,uCAAuC,EACvC,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,GAMvB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,SAAS,EACT,mBAAmB,GAMpB,MAAM,gBAAgB,CAAA;AAEvB,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,KAAwB,EACxB,YAAe,EACf,EAAE;IACF,MAAM,WAAW,GAAG,CAAC,KAAU,EAAE,YAAiB,EAAE,EAAE;QACpD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAC/B,OAAO,KAAK,CAAA;QACd,CAAC;QAED,IAAI,OAAO,KAAK,KAAK,OAAO,YAAY,EAAE,CAAC;YACzC,OAAO,YAAY,CAAA;QACrB,CAAC;QAED,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;YACrC,IAAI,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;gBAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC1B,OAAO,YAAY,CAAA;gBACrB,CAAC;qBAAM,CAAC;oBACN,OAAO,KAAK,CAAA;gBACd,CAAC;YACH,CAAC;YAED,KAAK,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAA;YACzD,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;gBACxC,KAAK,CAAC,GAAG,CAAC,GAAG,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAA;YAChE,CAAC,CAAC,CAAA;QACJ,CAAC;QAED,OAAO,KAAK,CAAA;IACd,CAAC,CAAA;IAED,OAAO,WAAW,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,YAAY,CAAM,CAAA;AACzE,CAAC,CAAA;AACD,cAAc,qBAAqB,CAAA","sourcesContent":["export * from './Common.Model.js'\nexport { compareVersions, isMinVersion } from './Version.js'\nexport {\n CrdtChannel,\n MIN_CRDT_HOST_VERSION,\n type CrdtAttachment,\n type CrdtInboundMessage,\n type CrdtOutboundMessage,\n type CrdtPostMessage,\n} from './CrdtChannel.js'\nexport { BlobStore } from './BlobStore.js'\nexport {\n AppSettingsError,\n APP_SETTINGS_TIMEOUT_MS,\n type AppSettingsErrorCode,\n} from './AppSettings.js'\nexport {\n PublicStorageError,\n PUBLIC_STORAGE_TIMEOUT_MS,\n PUBLIC_STORAGE_PUT_TIMEOUT_MS,\n MAX_PUBLIC_FILE_SIZE_BYTES,\n MIN_PUBLIC_FILE_EXPIRES_IN_SECONDS,\n validateExpiresIn,\n putPublicFileExpiryField,\n withDownloadUrlFallback,\n type PublicStorageErrorCode,\n type PublicStorageApi,\n type PublicStoragePutOptions,\n} from './PublicStorage.js'\nexport {\n PrivateStorageError,\n PRIVATE_STORAGE_TIMEOUT_MS,\n PRIVATE_STORAGE_PUT_TIMEOUT_MS,\n PRIVATE_STORAGE_GET_TIMEOUT_MS,\n MAX_PRIVATE_FILE_SIZE_BYTES,\n MIN_PRIVATE_FILE_EXPIRES_IN_SECONDS,\n MAX_PRIVATE_LINK_EXPIRES_IN_SECONDS,\n DEFAULT_PRIVATE_LINK_EXPIRES_IN_SECONDS,\n MAX_PRIVATE_PATH_LENGTH,\n MAX_PRIVATE_PATH_SEGMENTS,\n validatePrivatePath,\n validatePrivateExpiresIn,\n validateLinkExpiresIn,\n privateFileExpiryField,\n type PrivateStorageErrorCode,\n type PrivateStorageApi,\n type PrivateStorageReadApi,\n type PrivateStoragePutOptions,\n type PrivateStorageGetLinkOptions,\n} from './PrivateStorage.js'\nexport {\n AiChannel,\n MIN_AI_HOST_VERSION,\n type AiTool,\n type AiToolHandler,\n type AiInboundMessage,\n type AiOutboundMessage,\n type AiPostMessage,\n} from './AiChannel.js'\n\nexport const ensureDefaultValue = <T>(\n value: Partial<T> | null,\n defaultValue: T,\n) => {\n const ensureValue = (value: any, defaultValue: any) => {\n if (defaultValue === undefined) {\n return value\n }\n\n if (typeof value !== typeof defaultValue) {\n return defaultValue\n }\n\n if (typeof defaultValue === 'object') {\n if (Array.isArray(defaultValue)) {\n if (!Array.isArray(value)) {\n return defaultValue\n } else {\n return value\n }\n }\n\n value = value === undefined || value == null ? {} : value\n Object.keys(defaultValue).forEach((key) => {\n value[key] = ensureDefaultValue(value[key], defaultValue[key])\n })\n }\n\n return value\n }\n\n return ensureValue(value === undefined ? {} : value, defaultValue) as T\n}\nexport * from './PreviewScaling.js'\n"]}
@@ -1,4 +1,4 @@
1
- import type { FileData, Language, MenuEntry, CompanionUser, CompanionInformation } from '../Common/index.js';
1
+ import type { FileData, GetPrivateFile, GetPrivateFileLink, Language, ListPrivateFiles, MenuEntry, PrivateStorageResponse, CompanionUser, CompanionInformation } from '../Common/index.js';
2
2
  import type { CloseFrame, FrameOwnerChanged, OpenFrame, RootMenuEntry, SetFrameOwner } from '../Connector/Connector.Model.js';
3
3
  import type { OpenFrameOptions } from '../Common/Common.Model.js';
4
4
  export type { Language };
@@ -56,7 +56,9 @@ export type CompanionConnectorApiMessagesIn = ({
56
56
  type: 'frameOwnerChanged';
57
57
  } & FrameOwnerChanged) | ({
58
58
  type: 'messageFromVitreConnector';
59
- } & MessageFromVitreConnector);
59
+ } & MessageFromVitreConnector) | ({
60
+ type: 'privateStorageResponse';
61
+ } & PrivateStorageResponse);
60
62
  export type SetMenuMode = 'replace' | 'append';
61
63
  export type SetMenuOptions = {
62
64
  mode?: SetMenuMode;
@@ -81,5 +83,11 @@ export type CompanionConnectorApiMessagesOut = ({
81
83
  type: 'openCompanionFrame';
82
84
  } & OpenCompanionFrame) | ({
83
85
  type: 'sendMessageToVitreConnector';
84
- } & SendMessageToVitreConnector);
86
+ } & SendMessageToVitreConnector) | ({
87
+ type: 'listPrivateFiles';
88
+ } & ListPrivateFiles) | ({
89
+ type: 'getPrivateFile';
90
+ } & GetPrivateFile) | ({
91
+ type: 'getPrivateFileLink';
92
+ } & GetPrivateFileLink);
85
93
  export type { MenuEntry, RootMenuEntry };
@@ -1 +1 @@
1
- {"version":3,"file":"CompanionConnector.Model.js","sourceRoot":"","sources":["../../CompanionConnector/CompanionConnector.Model.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,wEAAwE;AACxE,wEAAwE;AACxE,uEAAuE;AACvE,uEAAuE;AACvE,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,uEAAuE;AACvE,OAAO;AACP,EAAE;AACF,uEAAuE;AACvE,8DAA8D;AAC9D,4EAA4E;AAC5E,8CAA8C","sourcesContent":["// Distinct API for connectors hosted on a la Vitre Companion (the mobile /\n// web app a user runs alongside the Vitre). The companion runs the same\n// app code but in a very different context — it has no Vitre device, no\n// shared space awareness, no notifications, no settings persistence, …\n// Rather than exposing the full Vitre `Connector` API with empty stubs\n// (which would silently swallow `setShareTarget`, `showNotification`,\n// `setVitreSettings`, …), the companion connector exposes ONLY what\n// genuinely applies here: declaring a menu, opening frames, and exchanging\n// opaque app messages with the matching Vitre `Connector` for the same\n// app.\n//\n// Anything not listed here is intentionally absent. The Vitre side has\n// the same surface restriction in the other direction: it can\n// `sendMessageToCompanionConnector` but companion connectors do NOT receive\n// device events, knock-knocks, settings, etc.\n\nimport type {\n FileData,\n Language,\n MenuEntry,\n CompanionUser,\n CompanionInformation,\n} from '../Common/index.js'\nimport type {\n CloseFrame,\n FrameOwnerChanged,\n OpenFrame,\n RootMenuEntry,\n SetFrameOwner,\n} from '../Connector/Connector.Model.js'\nimport type { OpenFrameOptions } from '../Common/Common.Model.js'\n\nexport type { Language }\n\n/// Snapshot of the authenticated companion user. Optional because the\n/// companion has guest sessions (no logged-in user) too.\n///\n/// Identity of the Vitre this companion is currently connected to. The\n/// connector only exists in the context of a live connection so this is\n/// always present once `initialize` fires.\n///\n/// `teamDomain` / `teamName` are optional because they aren't always\n/// known by the companion at the time the connector is initialized\n/// (e.g. guest sessions). The connector cannot observe later updates\n/// through this object — it is only refreshed on a new `initialize`.\n/// If you need the team identity and it is missing at init, fall back\n/// to `space` and accept the gap rather than waiting.\n/// The host of a companion connector IS the Vitre it is connected to, so\n/// `connector.hostInformation` carries the Vitre identity directly.\nexport type CompanionHostInformation = {\n id: string\n name: string\n color: string\n teamDomain?: string\n teamName?: string\n space: string\n}\n\n/**\n * @deprecated Use `CompanionHostInformation`. The host of a companion\n * connector IS the Vitre it is connected to, so `hostInformation` now\n * carries the Vitre identity directly (this used to be nested under\n * `CompanionHostInformation.connectedVitre`).\n */\nexport type ConnectedVitre = CompanionHostInformation\n\n/// `CompanionUser` / `CompanionInformation` now live in `Common` so the\n/// Frame module can surface `companionInformation` on companion-side frames\n/// too. Re-exported here for backward compatibility with existing\n/// `@lavitre/apps/CompanionConnector` consumers.\nexport type { CompanionUser, CompanionInformation }\n\n/// Declared by the companion connector at boot. Mirrors a subset of the\n/// Vitre `ConnectorOptions` — only `name`, `iconUrl` and `menu` apply.\n/// `shareTarget`, `settingsSchema`, `voiceActions` are Vitre-only and\n/// intentionally absent.\nexport type CompanionConnectorOptions = {\n name: string\n iconUrl?: string\n menu?: RootMenuEntry[]\n}\n\nexport type CompanionInitializeConnector = {\n hostInfo: CompanionHostInformation\n companionInfo: CompanionInformation\n /// Optional on purpose: a host may omit it for a generic connector that\n /// isn't tied to a single app. When present it is the routing key for\n /// `messageFromVitreConnector` / `sendMessageToVitreConnector`. The\n /// runtime warns (see `CompanionConnector` constructor) if it is missing\n /// so a misconfigured host surfaces at runtime rather than silently\n /// failing to route.\n appId?: string\n}\n\nexport type CompanionConnectorInitialized = {\n options: CompanionConnectorOptions\n}\n\n/// Payload a companion connector sends to the matching Vitre `Connector`\n/// (same `appId`). The Vitre connector receives the mirror message\n/// `messageFromCompanionConnector` with `fromCompanionId` set so it can\n/// reply targeted-back.\nexport type SendMessageToVitreConnector = {\n message: string\n fileData?: FileData\n}\n\n/// Payload the companion connector receives when its matching Vitre\n/// `Connector` calls `sendMessageToCompanionConnector`.\nexport type MessageFromVitreConnector = {\n message: string\n fileData?: FileData\n}\n\n/// Inbound to a companion connector (host → connector iframe).\nexport type CompanionConnectorApiMessagesIn =\n | ({ type: 'initialize' } & CompanionInitializeConnector)\n | {\n type: 'menuClicked'\n menuId: string\n isChecked: boolean\n tag: any\n }\n | { type: 'frameLoaded'; frameConnectorId: string }\n | { type: 'frameUnloaded'; frameConnectorId: string }\n | ({ type: 'frameOwnerChanged' } & FrameOwnerChanged)\n | ({ type: 'messageFromVitreConnector' } & MessageFromVitreConnector)\n\n/// How a companion connector's `setMenu` combines with the menu the\n/// Vitre-side `Connector` published for the same app.\n///\n/// `'replace'` (default, and the historical behaviour) — the companion\n/// connector's menu fully replaces the Vitre menu for this app on the\n/// companion: the Vitre-pushed entries are suppressed.\n///\n/// `'append'` — the companion connector's entries are added *after* the\n/// Vitre menu; both are rendered. Use this to contribute companion-only\n/// entries without hiding what the Vitre published.\nexport type SetMenuMode = 'replace' | 'append'\n\n/// Options for `CompanionConnector.setMenu`.\nexport type SetMenuOptions = {\n /// See `SetMenuMode`. Omitted ⇒ `'replace'`.\n mode?: SetMenuMode\n}\n\n/// Payload of the companion-side `openCompanionFrame` outbound. The\n/// companion's CompanionConnector calls this to ask the host to open\n/// (or focus) a frame full-page on this companion. If the Vitre is\n/// reachable the host also announces the open to it so a paired frame\n/// mounts there (same as the Vitre-driven open path, in reverse). The\n/// `frameConnectorId` MUST match the paired Vitre frame's id so the two\n/// frames bind on both sides.\nexport type OpenCompanionFrame = {\n frameConnectorId: string\n options: Omit<OpenFrameOptions, 'frameConnectorId'>\n}\n\n/// Outbound from a companion connector (connector iframe → host).\nexport type CompanionConnectorApiMessagesOut =\n | ({ type: 'connectorInitialized' } & CompanionConnectorInitialized)\n | { type: 'setRootMenu'; menu: RootMenuEntry[]; mode?: SetMenuMode }\n | ({ type: 'openFrame' } & OpenFrame)\n | ({ type: 'closeFrame' } & CloseFrame)\n | ({ type: 'setFrameOwner' } & SetFrameOwner)\n /// Open or focus a paired frame full-page on this companion. Distinct\n /// from `openFrame` because the host treats it as a navigation event\n /// (camera-share style) rather than a side-panel mount. See\n /// `OpenCompanionFrame`.\n | ({ type: 'openCompanionFrame' } & OpenCompanionFrame)\n | ({ type: 'sendMessageToVitreConnector' } & SendMessageToVitreConnector)\n\n/// Re-exported here for callers that want to declare `menu` entries\n/// without importing from two modules. `MenuEntry` originates in\n/// `../Common`; `RootMenuEntry` originates in `../Connector/Connector.Model`.\n/// Both are surfaced from here purely for caller convenience.\nexport type { MenuEntry, RootMenuEntry }\n"]}
1
+ {"version":3,"file":"CompanionConnector.Model.js","sourceRoot":"","sources":["../../CompanionConnector/CompanionConnector.Model.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,wEAAwE;AACxE,wEAAwE;AACxE,uEAAuE;AACvE,uEAAuE;AACvE,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,uEAAuE;AACvE,OAAO;AACP,EAAE;AACF,uEAAuE;AACvE,8DAA8D;AAC9D,4EAA4E;AAC5E,8CAA8C","sourcesContent":["// Distinct API for connectors hosted on a la Vitre Companion (the mobile /\n// web app a user runs alongside the Vitre). The companion runs the same\n// app code but in a very different context — it has no Vitre device, no\n// shared space awareness, no notifications, no settings persistence, …\n// Rather than exposing the full Vitre `Connector` API with empty stubs\n// (which would silently swallow `setShareTarget`, `showNotification`,\n// `setVitreSettings`, …), the companion connector exposes ONLY what\n// genuinely applies here: declaring a menu, opening frames, and exchanging\n// opaque app messages with the matching Vitre `Connector` for the same\n// app.\n//\n// Anything not listed here is intentionally absent. The Vitre side has\n// the same surface restriction in the other direction: it can\n// `sendMessageToCompanionConnector` but companion connectors do NOT receive\n// device events, knock-knocks, settings, etc.\n\nimport type {\n FileData,\n GetPrivateFile,\n GetPrivateFileLink,\n Language,\n ListPrivateFiles,\n MenuEntry,\n PrivateStorageResponse,\n CompanionUser,\n CompanionInformation,\n} from '../Common/index.js'\nimport type {\n CloseFrame,\n FrameOwnerChanged,\n OpenFrame,\n RootMenuEntry,\n SetFrameOwner,\n} from '../Connector/Connector.Model.js'\nimport type { OpenFrameOptions } from '../Common/Common.Model.js'\n\nexport type { Language }\n\n/// Snapshot of the authenticated companion user. Optional because the\n/// companion has guest sessions (no logged-in user) too.\n///\n/// Identity of the Vitre this companion is currently connected to. The\n/// connector only exists in the context of a live connection so this is\n/// always present once `initialize` fires.\n///\n/// `teamDomain` / `teamName` are optional because they aren't always\n/// known by the companion at the time the connector is initialized\n/// (e.g. guest sessions). The connector cannot observe later updates\n/// through this object — it is only refreshed on a new `initialize`.\n/// If you need the team identity and it is missing at init, fall back\n/// to `space` and accept the gap rather than waiting.\n/// The host of a companion connector IS the Vitre it is connected to, so\n/// `connector.hostInformation` carries the Vitre identity directly.\nexport type CompanionHostInformation = {\n id: string\n name: string\n color: string\n teamDomain?: string\n teamName?: string\n space: string\n}\n\n/**\n * @deprecated Use `CompanionHostInformation`. The host of a companion\n * connector IS the Vitre it is connected to, so `hostInformation` now\n * carries the Vitre identity directly (this used to be nested under\n * `CompanionHostInformation.connectedVitre`).\n */\nexport type ConnectedVitre = CompanionHostInformation\n\n/// `CompanionUser` / `CompanionInformation` now live in `Common` so the\n/// Frame module can surface `companionInformation` on companion-side frames\n/// too. Re-exported here for backward compatibility with existing\n/// `@lavitre/apps/CompanionConnector` consumers.\nexport type { CompanionUser, CompanionInformation }\n\n/// Declared by the companion connector at boot. Mirrors a subset of the\n/// Vitre `ConnectorOptions` — only `name`, `iconUrl` and `menu` apply.\n/// `shareTarget`, `settingsSchema`, `voiceActions` are Vitre-only and\n/// intentionally absent.\nexport type CompanionConnectorOptions = {\n name: string\n iconUrl?: string\n menu?: RootMenuEntry[]\n}\n\nexport type CompanionInitializeConnector = {\n hostInfo: CompanionHostInformation\n companionInfo: CompanionInformation\n /// Optional on purpose: a host may omit it for a generic connector that\n /// isn't tied to a single app. When present it is the routing key for\n /// `messageFromVitreConnector` / `sendMessageToVitreConnector`. The\n /// runtime warns (see `CompanionConnector` constructor) if it is missing\n /// so a misconfigured host surfaces at runtime rather than silently\n /// failing to route.\n appId?: string\n}\n\nexport type CompanionConnectorInitialized = {\n options: CompanionConnectorOptions\n}\n\n/// Payload a companion connector sends to the matching Vitre `Connector`\n/// (same `appId`). The Vitre connector receives the mirror message\n/// `messageFromCompanionConnector` with `fromCompanionId` set so it can\n/// reply targeted-back.\nexport type SendMessageToVitreConnector = {\n message: string\n fileData?: FileData\n}\n\n/// Payload the companion connector receives when its matching Vitre\n/// `Connector` calls `sendMessageToCompanionConnector`.\nexport type MessageFromVitreConnector = {\n message: string\n fileData?: FileData\n}\n\n/// Inbound to a companion connector (host → connector iframe).\nexport type CompanionConnectorApiMessagesIn =\n | ({ type: 'initialize' } & CompanionInitializeConnector)\n | {\n type: 'menuClicked'\n menuId: string\n isChecked: boolean\n tag: any\n }\n | { type: 'frameLoaded'; frameConnectorId: string }\n | { type: 'frameUnloaded'; frameConnectorId: string }\n | ({ type: 'frameOwnerChanged' } & FrameOwnerChanged)\n | ({ type: 'messageFromVitreConnector' } & MessageFromVitreConnector)\n | ({ type: 'privateStorageResponse' } & PrivateStorageResponse)\n\n/// How a companion connector's `setMenu` combines with the menu the\n/// Vitre-side `Connector` published for the same app.\n///\n/// `'replace'` (default, and the historical behaviour) — the companion\n/// connector's menu fully replaces the Vitre menu for this app on the\n/// companion: the Vitre-pushed entries are suppressed.\n///\n/// `'append'` — the companion connector's entries are added *after* the\n/// Vitre menu; both are rendered. Use this to contribute companion-only\n/// entries without hiding what the Vitre published.\nexport type SetMenuMode = 'replace' | 'append'\n\n/// Options for `CompanionConnector.setMenu`.\nexport type SetMenuOptions = {\n /// See `SetMenuMode`. Omitted ⇒ `'replace'`.\n mode?: SetMenuMode\n}\n\n/// Payload of the companion-side `openCompanionFrame` outbound. The\n/// companion's CompanionConnector calls this to ask the host to open\n/// (or focus) a frame full-page on this companion. If the Vitre is\n/// reachable the host also announces the open to it so a paired frame\n/// mounts there (same as the Vitre-driven open path, in reverse). The\n/// `frameConnectorId` MUST match the paired Vitre frame's id so the two\n/// frames bind on both sides.\nexport type OpenCompanionFrame = {\n frameConnectorId: string\n options: Omit<OpenFrameOptions, 'frameConnectorId'>\n}\n\n/// Outbound from a companion connector (connector iframe → host).\nexport type CompanionConnectorApiMessagesOut =\n | ({ type: 'connectorInitialized' } & CompanionConnectorInitialized)\n | { type: 'setRootMenu'; menu: RootMenuEntry[]; mode?: SetMenuMode }\n | ({ type: 'openFrame' } & OpenFrame)\n | ({ type: 'closeFrame' } & CloseFrame)\n | ({ type: 'setFrameOwner' } & SetFrameOwner)\n /// Open or focus a paired frame full-page on this companion. Distinct\n /// from `openFrame` because the host treats it as a navigation event\n /// (camera-share style) rather than a side-panel mount. See\n /// `OpenCompanionFrame`.\n | ({ type: 'openCompanionFrame' } & OpenCompanionFrame)\n | ({ type: 'sendMessageToVitreConnector' } & SendMessageToVitreConnector)\n /// Read-only private storage requests — list/get/getLink only (write\n /// stays vitre-only). See `CompanionConnector.privateStorage`.\n | ({ type: 'listPrivateFiles' } & ListPrivateFiles)\n | ({ type: 'getPrivateFile' } & GetPrivateFile)\n | ({ type: 'getPrivateFileLink' } & GetPrivateFileLink)\n\n/// Re-exported here for callers that want to declare `menu` entries\n/// without importing from two modules. `MenuEntry` originates in\n/// `../Common`; `RootMenuEntry` originates in `../Connector/Connector.Model`.\n/// Both are surfaced from here purely for caller convenience.\nexport type { MenuEntry, RootMenuEntry }\n"]}
@@ -1,4 +1,5 @@
1
1
  import type { FileData, OpenFrameOptions } from '../Common/index.js';
2
+ import type { PrivateStorageReadApi } from '../Common/PrivateStorage.js';
2
3
  import type { RootMenuEntry } from '../Connector/Connector.Model.js';
3
4
  import type { CompanionConnectorApiMessagesIn, CompanionConnectorApiMessagesOut, CompanionConnectorOptions, CompanionHostInformation, CompanionInformation, CompanionInitializeConnector, SetMenuOptions } from './CompanionConnector.Model.js';
4
5
  export declare class CompanionConnector {
@@ -13,7 +14,19 @@ export declare class CompanionConnector {
13
14
  onFrameOwnerChanged?: (frameConnectorId: string, owner: string) => void;
14
15
  onMessageFromVitreConnector?: (message: string, fileData?: FileData) => void;
15
16
  onMessageReceived?: (msg: CompanionConnectorApiMessagesIn) => void;
17
+ /**
18
+ * Read-only private storage — `list`/`get`/`getLink` only. The companion
19
+ * connects to a single Vitre's team, so scoping is the same as on the
20
+ * Vitre side (`'app'` default, `'shared'`). Writes stay vitre-only: a
21
+ * Vitre host that DOES support private storage still answers a
22
+ * `putPrivateFile`/`deletePrivateFile` from a companion with
23
+ * `error: 'unsupported'` — which is moot here since this type doesn't
24
+ * even expose `put`/`delete`. See the README "Private storage" section.
25
+ */
26
+ readonly privateStorage: PrivateStorageReadApi;
16
27
  constructor(postMessage: (message: CompanionConnectorApiMessagesOut, transfer?: Transferable[]) => void, initMessage: CompanionInitializeConnector, options: CompanionConnectorOptions);
28
+ private requestResolvers;
29
+ private resolveRequest;
17
30
  raiseMessage(msg: CompanionConnectorApiMessagesIn): void;
18
31
  setMenu(menu: RootMenuEntry[], options?: SetMenuOptions): void;
19
32
  openFrame(options: OpenFrameOptions): void;
@@ -21,6 +34,7 @@ export declare class CompanionConnector {
21
34
  setFrameOwner(frameConnectorId: string, owner: string): void;
22
35
  openCompanionFrame(frameConnectorId: string, options: Omit<OpenFrameOptions, 'frameConnectorId'>): void;
23
36
  sendMessageToVitreConnector(message: string, fileData?: FileData): void;
37
+ private postRequest;
24
38
  }
25
39
  type PostMessageOut = (message: CompanionConnectorApiMessagesOut, transfer?: Transferable[]) => void;
26
40
  export declare function initializeCompanionConnector<T extends CompanionConnector>(buildOptions: (host: CompanionHostInformation) => CompanionConnectorOptions | Promise<CompanionConnectorOptions>, createConnector: new (postMessage: PostMessageOut, initMessage: CompanionInitializeConnector, options: CompanionConnectorOptions) => T): Promise<T>;