@lavitre/apps 1.55.0 → 1.56.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +70 -0
- package/dist/Common/Common.Model.d.ts +126 -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/index.d.ts +1 -0
- package/dist/Common/index.js +1 -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 +13 -1
- package/dist/Connector/Connector.Model.js.map +1 -1
- package/dist/Connector/Connector.d.ts +12 -0
- package/dist/Connector/Connector.js +106 -0
- package/dist/Connector/Connector.js.map +1 -1
- package/dist/Frame/Frame.Model.d.ts +13 -1
- package/dist/Frame/Frame.Model.js.map +1 -1
- package/dist/Frame/Frame.d.ts +13 -0
- package/dist/Frame/Frame.js +107 -0
- package/dist/Frame/Frame.js.map +1 -1
- 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
|
@@ -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"]}
|
package/dist/Common/index.d.ts
CHANGED
|
@@ -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';
|
package/dist/Common/index.js
CHANGED
|
@@ -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) => {
|
package/dist/Common/index.js.map
CHANGED
|
@@ -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>;
|