@lavitre/apps 1.53.0 → 1.56.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.md +180 -0
  2. package/dist/Common/AppSettings.d.ts +34 -0
  3. package/dist/Common/AppSettings.js +35 -0
  4. package/dist/Common/AppSettings.js.map +1 -0
  5. package/dist/Common/Common.Model.d.ts +271 -0
  6. package/dist/Common/Common.Model.js.map +1 -1
  7. package/dist/Common/PrivateStorage.d.ts +249 -0
  8. package/dist/Common/PrivateStorage.js +158 -0
  9. package/dist/Common/PrivateStorage.js.map +1 -0
  10. package/dist/Common/PublicStorage.d.ts +140 -0
  11. package/dist/Common/PublicStorage.js +88 -0
  12. package/dist/Common/PublicStorage.js.map +1 -0
  13. package/dist/Common/index.d.ts +3 -0
  14. package/dist/Common/index.js +3 -0
  15. package/dist/Common/index.js.map +1 -1
  16. package/dist/CompanionConnector/CompanionConnector.Model.d.ts +11 -3
  17. package/dist/CompanionConnector/CompanionConnector.Model.js.map +1 -1
  18. package/dist/CompanionConnector/CompanionConnector.d.ts +14 -0
  19. package/dist/CompanionConnector/CompanionConnector.js +122 -0
  20. package/dist/CompanionConnector/CompanionConnector.js.map +1 -1
  21. package/dist/CompanionFrame/CompanionFrame.d.ts +13 -2
  22. package/dist/CompanionFrame/CompanionFrame.js.map +1 -1
  23. package/dist/Connector/Connector.Model.d.ts +29 -1
  24. package/dist/Connector/Connector.Model.js.map +1 -1
  25. package/dist/Connector/Connector.d.ts +60 -1
  26. package/dist/Connector/Connector.js +280 -1
  27. package/dist/Connector/Connector.js.map +1 -1
  28. package/dist/Frame/Frame.Model.d.ts +36 -2
  29. package/dist/Frame/Frame.Model.js.map +1 -1
  30. package/dist/Frame/Frame.d.ts +68 -3
  31. package/dist/Frame/Frame.js +326 -3
  32. package/dist/Frame/Frame.js.map +1 -1
  33. package/dist/Frame/SharedStreamPeer.d.ts +16 -0
  34. package/dist/Frame/SharedStreamPeer.js +74 -0
  35. package/dist/Frame/SharedStreamPeer.js.map +1 -0
  36. package/dist/Version.d.ts +1 -1
  37. package/dist/Version.js +1 -1
  38. package/dist/Version.js.map +1 -1
  39. package/package.json +1 -1
@@ -1 +1 @@
1
- {"version":3,"file":"Common.Model.js","sourceRoot":"","sources":["../../Common/Common.Model.ts"],"names":[],"mappings":"AA2lBA;;GAEG;AACH,MAAM,CAAN,IAAY,cAOX;AAPD,WAAY,cAAc;IACxB,wFAAwF;IACxF,uCAAqB,CAAA;IACrB,mDAAiC,CAAA;IACjC,kEAAkE;IAClE,qDAAmC,CAAA;IACnC,mFAAiE,CAAA;AACnE,CAAC,EAPW,cAAc,KAAd,cAAc,QAOzB;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,cAGX;AAHD,WAAY,cAAc;IACxB,mCAAiB,CAAA;IACjB,2CAAyB,CAAA;AAC3B,CAAC,EAHW,cAAc,KAAd,cAAc,QAGzB","sourcesContent":["export type DeviceType =\n | 'vitre'\n | 'guest'\n | 'vitreMini'\n | 'vitrePrimary'\n | 'vitreSecondary'\n | 'tableau'\n | 'vitreGuest'\n | 'companion'\n\nexport type Privacy = 'none' | 'muted' | 'blurred' | 'mutedSender'\n\nexport type Language = 'fr' | 'en' | 'it'\n\n/// A signed-in companion user. `isAdministrator` is derived host-side from\n/// `roles.includes('administrator')` and surfaced as a boolean so apps can\n/// gate features without hard-coding the magic role string; `roles` is still\n/// available for fine-grained checks.\nexport type CompanionUser = {\n id: string\n firstName: string\n lastName: string\n roles: string[]\n isAdministrator: boolean\n}\n\n/// A companion's own identity and runtime context. Surfaced as\n/// `connector.companionInformation` (CompanionConnector) and\n/// `frame.companionInformation` (companion-side Frame / CompanionFrame).\n/// Strictly distinct from the Vitre identity (`hostInformation`).\n///\n/// `name` is the companion's chosen display name — a mandatory field on the\n/// connect page (account fullname, mobile device name, or manually entered,\n/// stored locally). It is also what the Vitre shows as this companion peer's\n/// name. `user` is present only when signed in (guest sessions omit it).\n/// `language` / `origin` / `version` describe the companion runtime, not the\n/// Vitre. Undefined on Vitre-side frames (a Vitre has no companion identity).\nexport type CompanionInformation = {\n /// Stable identifier for this companion as a participant (the signed-in\n /// user id, or a fallback for guest sessions). Distinct from the Vitre's\n /// `hostInformation.device.id`. Apps that render the companion as a\n /// collaboration peer (cursors, awareness) should key on this.\n id: string\n name: string\n /// The companion participant's colour (cursor / awareness). Distinct from\n /// the Vitre's `hostInformation.device.color`.\n color: string\n user?: CompanionUser\n language: Language\n origin: string\n version?: string\n}\n\n/**\n * @deprecated Use string\n */\nexport type LegacyI18nMap = {\n fr: string\n en: string\n it: string\n}\nexport type I18nMap = string | LegacyI18nMap\n\nexport type FileData = {\n id?: string\n name: string\n mime: string\n data: ArrayBufferLike\n shareTargetId?: string\n}\n\nexport type DeviceScalingVersion = 'legacy' | 'rotationIndependent'\n\nexport type Ratio = 'ratio16_9' | 'ratio9_16'\n\nexport type CropMode = 'cropped' | 'notCropped'\n\nexport type DeviceScaling = {\n scale: number\n offsetX: number\n offsetY: number\n orientation?: Orientation\n orientationBy?: OrientationBy\n ratio?: Ratio\n cropMode?: CropMode\n version?: DeviceScalingVersion\n}\n\nexport type DeviceFullscreen = 'fullscreen' | 'localDevice' | 'notFullscreen'\n\nexport type Device = {\n id: string\n name: string\n color: string\n type: DeviceType\n privacy: Privacy\n mainDeviceId?: string\n /**\n * represent the scaling applied on the local camera stream when sending to this device\n */\n sendingScaling?: DeviceScaling\n orientation?: Orientation\n orientationBy?: OrientationBy\n fullscreen?: DeviceFullscreen\n}\n\nexport type TeamInfo = {\n id: string\n name: string\n domain: string\n}\n\nexport type HostInformation = {\n language: Language\n device: Device\n version?: string\n devicesInSpace: Device[]\n spaceTeam: TeamInfo\n owner: TeamInfo\n origin: string\n team: string\n teamId: string\n space: Space\n color: string\n privacy: Privacy\n guestInviteUrl: string\n displays: Display[]\n settings?: any\n vitreSettings: VitreSettings\n companionCode?: string\n /**\n * `true` when the frame iframe is loaded by a la Vitre **companion**\n * (i.e. the host is `lavitre-companion`, not a Vitre). Apps can use\n * this to pick the right SDK surface — `initializeCompanionFrame` /\n * `CompanionFrame` on the companion side, `initializeFrame` / `Frame`\n * on the Vitre side — and to branch UI / behaviour that genuinely\n * differs between the two contexts (e.g. show a \"Leave this frame\"\n * button on the companion that calls `closeOnCompanion()`, omit it on\n * the Vitre).\n *\n * Undefined / false on the Vitre side. Set by\n * `lavitre-companion/.../CompanionApps.State.fs:buildVitreLikeHostInformation`.\n * Backward-compat: old hosts simply omit the field, so apps that read\n * it as `?? false` keep working unchanged. Added 1.15.\n */\n isCompanion?: boolean\n}\n\nexport type SendMessageTo = {\n connectorId?: string\n deviceIds?: string[]\n message: string\n fileData?: FileData\n}\n\nexport type SendMessageToAll = {\n connectorId?: string\n message: string\n fileData?: FileData\n}\n\nexport type SendKnockKnock = {\n deviceIds?: string[]\n}\n\nexport type DeviceJoined = {\n device: Device\n}\n\nexport type DeviceLeft = {\n deviceId: string\n}\n\nexport type DeviceMessageReceived = {\n from: string\n message: string\n fileData?: FileData\n fromConnectorId?: string\n}\n\nexport type MenuCategory = {\n label: string\n description?: string\n order?: number\n}\n\nexport type NumberRange = {\n id: string\n min: number\n max: number\n value: number\n step: number\n}\n\nexport type Field = { type: 'numberRange' } & NumberRange\n\nexport type Availability = {\n vitre?: boolean\n companion?: boolean\n companionAdmin?: boolean\n}\n\n/**\n * Declares that clicking a MenuEntry on the companion opens a frame on\n * the companion side (and on the Vitre too, if `kind === 'normal'`).\n *\n * `kind === 'local'` — the frame lives only on the companion that opened\n * it; its lifecycle is independent of any frame on the Vitre.\n *\n * `kind === 'normal'` — the frame on the companion is paired with a\n * frame on the Vitre via the same `frameConnectorId`. Per-frame messages\n * and yjs CRDT updates flow between them transparently.\n */\nexport type CompanionFrameTarget = {\n kind: 'local' | 'normal'\n frameConnectorId: string\n options: Omit<OpenFrameOptions, 'frameConnectorId'>\n}\n\nexport type EntryType = 'button' | 'toggle' | 'companionOpenLink'\n\nexport type OverlayIcon = {\n iconUrl?: string\n iconUrlChecked?: string\n iconUrlUnchecked?: string\n}\n\nexport type MenuEntry = {\n label: string\n id: string\n tag?: any\n order?: number\n hasConfirm?: boolean\n isChecked?: boolean\n isDisabled?: boolean\n category?: MenuCategory\n maskIconUrl?: string\n iconUrl?: string\n maskIconUrlChecked?: string\n iconUrlChecked?: string\n overlayIcons?: OverlayIcon[]\n menu?: MenuEntry[]\n description?: string\n isCloseOnClick?: boolean\n type?: EntryType\n focus?: boolean\n field?: Field\n linkUrl?: string\n radioGroup?: string\n availability?: Availability\n /**\n * If set, the host opens a companion frame when this entry is clicked\n * on the companion. The connector does not have to react to the\n * `menuClicked` event for this case — the frame opens automatically.\n *\n * Only honored when `availability.companion === true`.\n */\n opensCompanionFrame?: CompanionFrameTarget\n}\n\nexport type Size = {\n width: number\n height: number\n}\n\nexport type Rect = {\n x: number\n y: number\n width: number\n height: number\n}\n\nexport type Display = {\n bounds: Rect\n}\n\nexport type MonitorReference =\n | { type: 'contentMonitor' }\n | { type: 'monitorIndex'; index: number }\n\nexport type LayoutPosition = {\n /**\n * @deprecated Use left\n */\n x?: string\n /**\n * @deprecated Use top\n */\n y?: string\n width?: string\n height?: string\n left?: string\n top?: string\n right?: string\n bottom?: string\n centerX?: string\n centerY?: string\n monitor?: MonitorReference\n isFullscreen?: boolean\n}\n\nexport type DeviceRule = { deviceType?: DeviceType }\n\nexport type LayoutPositionRule = { type: 'deviceRule' } & DeviceRule\n\nexport type LayoutPositionWithRules = {\n width?: string\n height?: string\n left?: string\n top?: string\n right?: string\n bottom?: string\n centerX?: string\n centerY?: string\n monitor?: MonitorReference\n isFullscreen?: boolean\n rules?: LayoutPositionRule[]\n}\n\nexport type ViewMode = 'frame' | 'overlay'\n\nexport type FramePrivacy = 'shared' | 'pinned' | 'local'\n\n/**\n * Audience filter for the companion-frame open-on-companion behaviour. See\n * `CompanionFrameOption`. `'all'` means every connected companion is\n * targeted; `'administrator'` means only companions whose authenticated\n * user has the `administrator` role.\n */\nexport type CompanionFrameAudience = 'all' | 'administrator'\n\n/**\n * Declares how an opened frame should surface on connected companions. Lives\n * on `OpenFrameOptions` so the behaviour is decided per `connector.openFrame`\n * call. Companion side honours this at `FrameOpenedByVitre` reception time\n * (see `CompanionApps.State.fs`):\n *\n * - `autoOpen`: when set and the audience matches, the companion\n * auto-navigates to the new frame full-page IF it is\n * currently on the main Vitre page. If it is busy\n * (already on a frame, camera-share, etc.) the\n * auto-open is suppressed and a menu entry is added\n * to the CURRENT page's options instead. Auto-open\n * never preempts a busy companion.\n *\n * - `menuVisibility`: when set, a menu entry is added on the companion\n * side (in the current frame's options menu) for the\n * target audience, regardless of `autoOpen`. The\n * entry, when clicked, navigates to the frame.\n *\n * - `url`: REQUIRED. The URL the companion loads in its own\n * paired iframe. This is intentionally separate from\n * the Vitre frame's `OpenFrameOptions.url` so the\n * companion can present a different UI (and load its\n * own companion-frame entry point, e.g.\n * `companionFrame.html` initialised with\n * `initializeCompanionFrame`). The companion frame is\n * paired with the Vitre frame by the same\n * `frameConnectorId`, so per-frame messages and yjs\n * CRDT updates still flow between them.\n *\n * - `showBackButton`: controls the host's own \"back\" affordance on the\n * companion's full-page frame. The companion renders\n * the frame chrome-free (no la Vitre header) except a\n * single back button — the same control as the\n * camera-share page — that dismisses the frame. Set\n * `false` to hide it (e.g. when the app draws its own\n * close UI); the user can still leave via the device /\n * browser back gesture. Defaults to `true` (shown).\n *\n * - `edgeToEdge`: lets the frame cover the companion's whole surface,\n * system bars included; the app then keeps its controls\n * clear of them with `frame.safeAreaInsets`. See the\n * field doc.\n *\n * `url` is mandatory; `autoOpen` / `menuVisibility` / `showBackButton` /\n * `edgeToEdge` are independent and may be set together. If `autoOpen` and `menuVisibility`\n * are both absent the companion mounts nothing — no navigation, no menu —\n * and only the Vitre-side frame is shown.\n */\n/**\n * Subset of `MenuEntry` used to customise the companion menu entry that\n * (re)opens this companion frame — the entry surfaced when an `autoOpen` is\n * suppressed because the companion was busy, or added via `menuVisibility`.\n * Only the fields relevant to a host-driven open are exposed; the entry's\n * `id` and click behaviour are owned by the host. Any field left unset falls\n * back to the frame's `name` (label), no icon, and default ordering.\n */\nexport type CompanionFrameOpenMenuEntry = Pick<\n MenuEntry,\n 'label' | 'maskIconUrl' | 'iconUrl' | 'category' | 'description' | 'order'\n>\n\nexport type CompanionFrameOption = {\n url: string\n autoOpen?: CompanionFrameAudience\n menuVisibility?: CompanionFrameAudience\n /**\n * @deprecated Renamed to `showCloseButton`. Still honoured for backward\n * compatibility, but `showCloseButton` takes precedence when both are set.\n */\n showBackButton?: boolean\n /**\n * Whether the full-page companion frame shows the host's close button (the\n * control that dismisses the frame). Defaults to `true` when unset. Renamed\n * from the deprecated `showBackButton`.\n */\n showCloseButton?: boolean\n /**\n * Customises the companion menu entry that (re)opens this frame — the\n * busy-`autoOpen` fallback entry or the `menuVisibility` entry. Omit to\n * label the entry with the frame's `name` (no icon / category).\n */\n openMenuEntry?: CompanionFrameOpenMenuEntry\n /**\n * Whether the full-page companion frame covers the companion's whole\n * surface, system bars included (Android edge-to-edge: the navigation bar\n * is drawn translucent over the content). Set `true` only when the app\n * shifts its own controls with `frame.safeAreaInsets` — or with the\n * `--lavitre-safe-area-inset-*` CSS variables the SDK sets from it. When\n * unset or `false` the host keeps the iframe clear of the bars itself, so\n * a frame that knows nothing about insets is never covered. Added 1.51.\n */\n edgeToEdge?: boolean\n}\n\nexport type PositionType = 'Local' | 'Synced'\n\nexport type Interaction = 'notAllowed' | 'autoActiveOnFullscreen' | 'allowed'\n\nexport type BorderMode = 'borderLess' | 'border'\n\nexport type BorderOptions = {\n mode: BorderMode\n showToggleInMenu?: boolean\n}\n\nexport type StreamCapture = {\n data: ArrayBufferLike\n}\n\nexport type VoiceAction = {\n id: string\n message: I18nMap\n}\n\nexport type VoiceActionDetection = {\n id: string\n message: string\n language: string\n confidence: number\n}\n\nexport type OpenFrameOptions = {\n frameConnectorId: string\n streamId?: string\n name: string\n url: string\n size?: Size\n minSize?: Size\n maxSize?: Size\n startPosition?: LayoutPosition\n startPositions?: LayoutPositionWithRules[]\n /**\n * @deprecated Use startPosition.isFullscreen\n */\n startMode?: FrameStartMode\n /**\n * @deprecated Use interaction property\n */\n touchMode?: FrameTouchMode\n interaction?: Interaction\n allowFullscreen?: boolean\n menuVisibility?: MenuVisibility\n /**\n * @deprecated Use menuVisibility property vitre v20\n */\n hideMenu?: boolean\n startInteractive?: boolean\n resizeMode?: ResizeMode\n border?: BorderOptions\n data?: any\n file?: FileData\n mode?: ViewMode\n privacy?: FramePrivacy\n positionType?: PositionType\n voiceActions?: VoiceAction[]\n state?: Record<string, any>\n visibility?: Visibility\n closable?: boolean\n closeLabel?: string\n /**\n * Optional declaration of how this frame should surface on connected\n * companions. See `CompanionFrameOption`. When omitted the companion\n * side ignores the open (no auto-navigation, no menu) — the same\n * behaviour pre-1.13.\n */\n companionFrame?: CompanionFrameOption\n /**\n * Optional id of the device (see `HostInformation.devicesInSpace[].id`)\n * that should *own* the shared frame. The owner drives the languette\n * colour and, when it is a Vitre, takes over hosting the frame so it\n * survives the opener disconnecting (ownership transfer). When omitted\n * the opener owns the frame, as before. Change it afterwards with\n * `connector.setFrameOwner(frameConnectorId, owner)`.\n */\n owner?: string\n /**\n * SDK 1.32 — when `true`, the `file` is delivered ONLY to the opening\n * Vitre. The frame still opens and syncs on other peers, but the file\n * bytes are not propagated and the remote frames open without it. The\n * `data` field keeps syncing normally. The host strips the file before\n * cross-vitre sync — this is purely sender-side, so no peer-version gate\n * is needed (older receivers simply get a frame with no file, a state\n * they already handle). Has no effect when no `file` is provided.\n */\n localFile?: boolean\n /**\n * Icon shown for this frame's shared content on connected companions. A\n * bitmap (full colour). May be a path relative to the connector URL — the\n * host resolves it to an absolute URL. When both `iconUrl` and `maskIconUrl`\n * are set the companion prefers `maskIconUrl`. When neither is set the\n * companion falls back to the app icon (`ConnectorOptions.iconUrl`).\n */\n iconUrl?: string\n /**\n * Monochrome mask icon for this frame's shared content, tinted by the\n * companion theme (CSS `mask`). May be relative to the connector URL —\n * resolved absolute by the host. Preferred over `iconUrl` when both are set.\n */\n maskIconUrl?: string\n /**\n * CSS background applied to this frame's shared-content surface on the\n * Vitre (and on peer Vitres / tableaux showing it). Any CSS `background`\n * value — a colour, gradient, or `url(...)`. When set it overrides the\n * default surface background (`.lavitre-shared-object-content`, normally\n * black). Not resolved against the connector URL: pass an absolute URL if\n * you reference an image. When omitted the default background is kept.\n */\n background?: string\n /**\n * CSS `box-shadow` applied to this frame's shared-content surface on the\n * Vitre (and on peer Vitres / tableaux showing it). When set it overrides\n * the default surface shadow (`.lavitre-shared-object-content`). Pass\n * `'none'` to remove the shadow. When omitted the default shadow is kept.\n */\n boxShadow?: string\n /**\n * CSS `drop-shadow` filter applied to this frame's shared-content surface on\n * the Vitre (and on peer Vitres / tableaux showing it). The value is the\n * argument of the CSS `drop-shadow()` filter function — e.g.\n * `'0 4px 8px rgba(0,0,0,.5)'` — which the host wraps as\n * `filter: drop-shadow(<value>)`. Unlike `boxShadow` it follows the rendered\n * alpha shape, so it casts a shadow around non-rectangular / transparent\n * content (pair it with a transparent `background`). Pass `'none'` to remove\n * any filter. When omitted no drop-shadow filter is applied.\n */\n dropShadow?: string\n /**\n * CSS `backdrop-filter: blur(...)` applied to this frame's shared-content\n * surface on the Vitre (and on peer Vitres / tableaux showing it). The value\n * is the argument of the CSS `blur()` function — e.g. `'8px'` — which the\n * host wraps as `backdrop-filter: blur(<value>)`. It blurs whatever is\n * *behind* the surface (frosted-glass effect), so pair it with a translucent\n * `background`. Pass `'none'` to remove the backdrop filter. When omitted no\n * backdrop blur is applied.\n */\n backdropBlur?: string\n /**\n * Name to report for this frame in usage analytics (\"insights\"), instead of\n * the app's own name. A single app can open several kinds of frames — e.g.\n * Carbone opens \"Page blanche\", \"PDF\", \"Image\" — and by default every frame\n * is recorded under the app name (\"Carbone\"). Set `insightsName` per open to\n * distinguish them in the stats. When omitted the analytics fall back to the\n * current behaviour (the app name, then the frame `name`). Purely a reporting\n * label — it does not affect the frame UI (`name` still drives the visible\n * label) and never reaches other peers.\n */\n insightsName?: string\n}\n\n/**\n * Visual style of a frame's shared-content surface and its companion icon,\n * settable at open time (subset of `OpenFrameOptions`) and updatable at any\n * time with `connector.setChromeStyle(frameConnectorId, style)`. Every field\n * is optional: a field left `undefined` keeps the current value; pass an empty\n * string to clear an override back to the host default (e.g. `background: ''`).\n */\nexport type ChromeStyle = {\n /** See `OpenFrameOptions.background`. */\n background?: string\n /** See `OpenFrameOptions.boxShadow`. */\n boxShadow?: string\n /** See `OpenFrameOptions.dropShadow`. */\n dropShadow?: string\n /** See `OpenFrameOptions.backdropBlur`. */\n backdropBlur?: string\n /** See `OpenFrameOptions.iconUrl` (companion icon, bitmap). */\n iconUrl?: string\n /** See `OpenFrameOptions.maskIconUrl` (companion icon, monochrome mask). */\n maskIconUrl?: string\n}\n\n/**\n * @deprecated Use interaction property\n */\nexport enum FrameTouchMode {\n // Host will only allow manipulations. Touch events will not be forwarded to the webview\n ReadOnly = 'readonly',\n FullscreenOnly = 'fullscreenOnly',\n // Host will show a toggle button for interacting with the webview\n HostButtonInOut = 'hostButtonInOut',\n HostButtonMinimizeOnFullscreen = 'hostButtonMinimizeOnFullscreen',\n}\n\n/**\n * @deprecated Use startPosition.isFullscreen\n */\nexport enum FrameStartMode {\n Window = 'window',\n Fullscreen = 'fullscreen',\n}\n\nexport type ResizeMode =\n /**\n * @deprecated The method should not be used\n */\n | 'scale'\n /**\n * @deprecated The method should not be used\n */\n | 'resize'\n /**\n * @deprecated The method should not be used\n */\n | 'resizeAndKeepRatio'\n | 'no'\n | 'uniformRenderTransform'\n | 'freeRenderTransform'\n | 'uniformResize'\n | 'freeResize'\n\nexport type VideoContentHint = 'motion' | 'detail'\n\nexport type MenuClicked = {\n menuId: string\n isChecked: boolean\n tag: any | undefined\n}\n\nexport type LoadedFrame = {\n src: string\n name: string\n frameConnectorId: string\n}\n\nexport type LocalConnectorMessageReceived = {\n data: any\n fileData?: FileData\n from?: string\n}\n\nexport type SendToLocalFrame = {\n frameConnectorId?: string\n data: any\n fileData?: FileData\n}\n\nexport type EnumerateLoadedFramesCompleted = {\n requestId: string\n frames: LoadedFrame[]\n}\n\nexport type EnumerateLoadedFrames = {\n requestId: string\n}\n\nexport type PrivacyChanged = {\n privacy: Privacy\n}\n\nexport type MessageTargetCompanion = {\n type: 'companion'\n companionConnectionId: string\n}\n\nexport type MessageTarget = MessageTargetCompanion\n\n/**\n * A peer (Vitre or companion) that currently has a given frame open on\n * its side. Identified by the host's connection id so apps can address\n * it individually with the per-peer messaging APIs.\n */\nexport type FramePeer = {\n peerId: string\n deviceType: DeviceType\n name?: string\n}\n\n/**\n * Companion frame peer-presence wire events.\n *\n * `CompanionFramePeersUpdated` is the authoritative full snapshot — it\n * carries the complete current peer set and fires on every change.\n * `CompanionFramePeerJoined` / `CompanionFramePeerLeft` are convenience\n * incremental events derived from the same stream. Consumers should\n * subscribe to ONE model (snapshot OR incremental pair), not both, to\n * avoid double-counting every transition.\n */\nexport type CompanionFramePeerJoined = {\n peer: FramePeer\n}\n\nexport type CompanionFramePeerLeft = {\n peerId: string\n}\n\nexport type CompanionFramePeersUpdated = {\n peers: FramePeer[]\n}\n\nexport type AppMessage = {\n data: any\n fileData?: FileData\n target?: MessageTarget\n}\n\nexport type CameraExposureValue = {\n type: 'manual'\n exposure: number\n compensation: number\n}\n\nexport type CameraExposureAuto = {\n type: 'auto'\n}\n\nexport type CameraSettings = {\n exposure: CameraExposureAuto | CameraExposureValue\n deviceId?: string\n deviceName?: string\n}\n\nexport type StreamUsage = 'mainStream' | 'sharedStream'\n\nexport type Orientation = 'left' | 'right' | 'top' | 'bottom'\nexport type OrientationBy = 'system' | 'emulated'\n\nexport type ConnectedMediaDevice = {\n deviceId: string\n groupId: string\n kind: MediaDeviceKind\n label: string\n inUseBy: StreamUsage[]\n orientation?: Orientation\n orientationBySystem?: boolean\n}\n\nexport type AuthenticationMode = 'open' | 'userAccount'\n\nexport type SecuritySettings = {\n authentication: AuthenticationMode\n}\n\nexport type GuestSpace = {\n type: 'guestSpace'\n space: string\n teamDomain: string\n label: string\n}\n\nexport type TeamSpace = {\n type: 'teamSpace'\n space: string\n}\n\nexport type Space = GuestSpace | TeamSpace\n\n/**\n * Snapshot of the current active preset's noise filter selection.\n *\n * `active` and entries in `available` are the string ids of the F#\n * `Settings.Audio.AudioFilterLevel` enum. The current set is:\n *\n * \"none\" | \"rnnoise\" | \"rnnoise2\" | \"speex\" | \"noisegate\" | \"deepfilternet3\"\n *\n * Apps should treat the list as open — newer la Vitre builds may surface\n * additional filter ids the app doesn't know about. Render unknown ids\n * gracefully (e.g. as a generic option) rather than asserting on the set.\n */\nexport type AudioFilterView = {\n active: string\n available: string[]\n}\n\n/**\n * User-editable subset of the voice-profile chain (the \"custom\" profile).\n * Only meaningful when the active profile is \"custom\"; for the four frozen\n * profiles an app shows their fixed values read-only from its own table.\n */\nexport type CustomVoiceProfileView = {\n /** EQ presence (clarity) gain, dB. */\n presenceDb: number\n /** Compressor threshold, dB. */\n compThresholdDb: number\n /** Compressor ratio, >= 1. */\n compRatio: number\n /** De-esser sibilance cut, dB (negative). */\n deEsserCutDb: number\n}\n\nexport type CustomVoiceProfileSettingsSetter = {\n presenceDb?: number\n compThresholdDb?: number\n compRatio?: number\n deEsserCutDb?: number\n}\n\n/**\n * Voice profile (EQ + compressor + de-esser preset) applied for every\n * filter — including `none`. Ids:\n *\n * \"naturel\" | \"broadcast\" | \"douce\" | \"antifatigue\" | \"custom\"\n */\nexport type VoiceProfileView = {\n active: string\n available: string[]\n /** Persisted custom params (always present; edited only when\n * `active === 'custom'`). */\n custom: CustomVoiceProfileView\n}\n\n/**\n * DeepFilterNet 3 live-tunable knobs.\n *\n * `inputGainDb` and `wetDryMix` exist server-side but are intentionally\n * NOT exposed to apps — the SDK contract only covers the noise-reduction\n * tuning knobs that make sense in a \"voice quality\" UI.\n */\nexport type Dfn3View = {\n /** Suppression cap, 0..100 dB. Higher = more aggressive denoising. */\n attenLimDb: number\n /** Post-filter strength, 0..0.1. 0 disables it. */\n postFilterBeta: number\n}\n\nexport type Dfn3SettingsSetter = {\n attenLimDb?: number\n postFilterBeta?: number\n}\n\nexport type AudioSettings = {\n volume: number\n isMuted: boolean\n selectedPreset: string\n audioPresets: string[]\n /**\n * The following three are optional on the wire — older la Vitre builds\n * don't emit them. When undefined, treat as \"feature not available on\n * this Vitre\" rather than as a default value.\n */\n filter?: AudioFilterView\n voiceProfile?: VoiceProfileView\n dfn3?: Dfn3View\n}\n\nexport type AudioSettingsSetter = {\n volume?: number\n isMuted?: boolean\n selectedPreset?: string\n /**\n * Use one of `AudioFilterView.available` ids — unknown values are\n * silently dropped host-side rather than crashing the audio pipeline.\n */\n filter?: string\n voiceProfile?: string\n /**\n * Partial setter — only the fields present in the object are written.\n * Existing DFN3 properties not listed here (including `inputGainDb`\n * and `wetDryMix` which apps cannot manipulate) are preserved.\n */\n dfn3?: Dfn3SettingsSetter\n /**\n * Partial setter for the \"custom\" voice profile knobs. Only applied\n * when the active voice profile is \"custom\"; persisted regardless.\n */\n customVoiceProfile?: CustomVoiceProfileSettingsSetter\n}\n\nexport type VitreSettings = {\n availableMediaDevices: ConnectedMediaDevice[]\n audioSettings: AudioSettings\n cameraSettings: CameraSettings\n security: SecuritySettings\n spaces: Space[]\n currentSpace: Space\n language: Language\n color: string\n name?: string\n}\n\nexport type VitreSettingsSetter = {\n cameraSettings?: CameraSettings\n audioSettings?: AudioSettingsSetter\n}\n\nexport type DeviceTarget = 'all' | 'single'\n\nexport type KnockKnock = {\n from: Device\n target: DeviceTarget\n}\n\nexport type AppId = string\n\nexport type ShareFileRequest = {\n fileData: FileData\n targetAppId?: AppId\n /** SDK 1.20 — explicit owner device id for the resulting share. */\n owner?: string\n}\n\nexport type ShareDataRequest = {\n url: string\n targetAppId?: AppId\n /** SDK 1.20 — explicit owner device id for the resulting share. */\n owner?: string\n}\n\nexport type SaveSettings = {\n settings: any\n}\n\nexport type SettingsUpdated = {\n settings: any\n}\n\nexport type ChangeTeamSpace = {\n space: string\n}\n\nexport type ChangeTeamSpaceGuest = {\n space: string\n teamDomain: string\n}\n\nexport type NotificationButton = {\n id: string\n tag?: any\n iconUrl: string\n dismissOnClick?: boolean\n}\n\nexport type NotificationInfo = {\n id: string\n message: string\n iconUrl: string\n buttons?: NotificationButton[]\n closeTimeout?: number\n}\n\nexport type HideNotification = {\n id: string\n}\n\nexport type NotificationDismissed = {\n id: string\n}\n\nexport type NotificationButtonClicked = {\n id: string\n buttonId: string\n tag?: any\n}\n\nexport type DevicePrivacyChanged = { device: Device }\n\nexport type SDKInitRequest = {\n type: 'SDKInitRequest'\n version: string\n}\n\nexport type ChangePrivacy = {\n privacy: Privacy\n}\n\nexport type DeviceFrameReference = {\n frameConnectorId: string\n deviceId: string\n}\n\nexport type PendingDevicesInfo = {\n pendingDevices: Device[]\n}\n\nexport type EventTelemetry = {\n name: string\n properties?: Record<string, any>\n}\n\nexport type StartEventTelemetry = { name: string }\n\nexport type DeviceFullscreenUpdated = {\n deviceId: string\n fullscreen: DeviceFullscreen\n}\n\nexport type PositionUpdated = {\n position: Rect\n isFullscreen: boolean\n zIndex: number\n}\n\n/**\n * Distances, in CSS px of the frame's own viewport, from each edge of the\n * frame to the nearest edge of the area the host guarantees free of system\n * UI (Android navigation bar, display cutout, …). All zero unless the host\n * runs the frame edge-to-edge (`CompanionFrameOption.edgeToEdge`). Added 1.51.\n */\nexport type SafeAreaInsets = {\n top: number\n right: number\n bottom: number\n left: number\n}\n\nexport type SafeAreaInsetsUpdated = {\n safeAreaInsets: SafeAreaInsets\n}\n\nexport type Visibility = 'hidden' | 'visible' | 'visibleInFullscreenOnly'\nexport type MenuVisibility = 'hidden' | 'visible' | 'visibleInFullscreenOnly'\n\nexport type VisibilityChanged = {\n visibility: Visibility\n}\n\nexport type SetVisibility = { visibility: Visibility }\n\nexport type DeviceScalingUpdated = {\n deviceId: string\n sendingScaling: DeviceScaling\n orientation: Orientation\n orientationBy: OrientationBy\n}\n\nexport type UpdateStateEntry =\n | {\n action: 'add'\n key: string\n value: any\n }\n | {\n action: 'addOwned'\n key: string\n value: any\n }\n | {\n action: 'remove'\n key: string\n }\n\nexport type UpdatedStateEntry =\n | {\n action: 'add'\n key: string\n value: any\n }\n | {\n action: 'remove'\n key: string\n }\n | {\n action: 'addOwned'\n key: string\n value: any\n owner: string\n }\n\nexport type UpdateState = {\n updates: UpdateStateEntry[]\n}\n\nexport type ReplacedBy = 'local' | 'remote'\n\nexport type StateReplaced = {\n state: Record<string, any>\n delta: UpdatedStateEntry[]\n replacedBy: ReplacedBy\n}\n\nexport type GetStats = { requestId: string }\n\nexport type SetReducedAudioMode = { enabled: boolean }\n\nexport type DeviceTransceiverWebRTCStats = {\n deviceId: string\n transceiverId: string\n receiverStats?: any[]\n receiverStatsError?: string\n senderStats?: any[]\n senderStatsError?: string\n videoSendingParameters?: VideoSendingParameters\n /** Since 1.44: label of the outgoing track (originalTrack when the host wraps it). Absent on older hosts; explicit null on newer hosts when the transceiver has no sender track. */\n trackLabel?: string\n /** Since 1.44: sender track getSettings(), unwrapped via originalTrack when present. Absent on older hosts; null on newer hosts without a sender track. */\n trackSettings?: MediaTrackSettings\n /** Since 1.44: sender track getConstraints(). Absent on older hosts; null on newer hosts without a sender track. */\n trackConstraints?: MediaTrackConstraints\n /** Since 1.44: sender track muted flag. Absent on older hosts; null on newer hosts without a sender track. */\n trackMuted?: boolean\n /** Since 1.44: sender track enabled flag. Absent on older hosts; null on newer hosts without a sender track. */\n trackEnabled?: boolean\n /** Since 1.44: host sending parameters isEnabled (false under confidentiality). Absent on older hosts; null on newer hosts without a sender track. */\n sendingEnabled?: boolean\n}\n\nexport type MemoryInfo = {\n slotsInUse: number\n slots: number\n mbAvailable?: number\n}\n\nexport type VideoSendingParameters = {\n size?: Size\n bitrate?: number\n}\n\nexport type StatsResponse = {\n requestId: string\n webrtcStats: DeviceTransceiverWebRTCStats[]\n memory?: MemoryInfo\n cpuUsage?: number\n audioFilter?: string\n}\n\nexport type ConnectionCodeUpdated = {\n companionCode?: string\n}\n\nexport type FieldUpdated = {\n field: Field\n}\n\nexport type SendToSerialPort = {\n com: number\n baudRate: number\n readTimeout: number\n ackLineStartsWith?: string\n nackLineStartsWith?: string\n lines: string[]\n}\n\n/// Ask the host for access to a serial port. Resolves with the granted port\n/// name (empty string if denied/cancelled).\n/// - `port` given: the host pre-grants that port (so the next\n/// `navigator.serial.requestPort()` resolves to it silently) and resolves\n/// with `port`.\n/// - `port` omitted: the host shows its port-picker; resolves with the port\n/// the user chose (and pre-grants it).\n/// Honoured only when the app holds the WebSerial authorization.\nexport type RequestSerialPortAccess = {\n port?: string\n}\n\n/// Reply to RequestSerialPortAccess. On success `port` is the granted port\n/// name. On failure `port` is omitted and `reason` is one of the failure codes\n/// (the SDK rejects the promise with that reason).\nexport type SerialPortAccessReason = 'denied' | 'cancelled' | 'timeout'\nexport type SerialPortAccessResult = {\n port?: string\n reason?: SerialPortAccessReason\n}\n\nexport type StreamSizeUpdate = {\n deviceId: string\n size: Size\n}\n\nexport type RequestStreamSizeUpdate = {\n updates: StreamSizeUpdate[]\n}\n\nexport type DisconnectGuests = {\n deviceIds: string[]\n}\n\nexport type Characteristic = {\n uuid: string\n description: string\n properties: string\n}\n\nexport type OpenBTService = {\n serviceId: string\n requestId: string\n}\n\nexport type CloseBTService = {\n handleId: string\n}\n\nexport type WriteToCharacteristic = {\n handleId: string\n uuid: string\n buffer: ArrayBufferLike\n}\n\nexport type BluetoothFromApp =\n | ({ '@BluetoothFromApp': 'openBTService' } & OpenBTService)\n | ({ '@BluetoothFromApp': 'closeBTService' } & CloseBTService)\n | ({ '@BluetoothFromApp': 'writeToCharacteristic' } & WriteToCharacteristic)\n\nexport type OpenBTServiceResponseData = {\n requestId: string\n handleId: string\n characteristics: Characteristic[]\n}\n\nexport type OpenBTServiceResponse = {\n requestId: string\n isSuccess: boolean\n response?: OpenBTServiceResponseData\n error?: string\n}\n\nexport type BluetoothToApp = {\n '@BluetoothToApp': 'openBTServiceResponse'\n} & OpenBTServiceResponse\n"]}
1
+ {"version":3,"file":"Common.Model.js","sourceRoot":"","sources":["../../Common/Common.Model.ts"],"names":[],"mappings":"AA2lBA;;GAEG;AACH,MAAM,CAAN,IAAY,cAOX;AAPD,WAAY,cAAc;IACxB,wFAAwF;IACxF,uCAAqB,CAAA;IACrB,mDAAiC,CAAA;IACjC,kEAAkE;IAClE,qDAAmC,CAAA;IACnC,mFAAiE,CAAA;AACnE,CAAC,EAPW,cAAc,KAAd,cAAc,QAOzB;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,cAGX;AAHD,WAAY,cAAc;IACxB,mCAAiB,CAAA;IACjB,2CAAyB,CAAA;AAC3B,CAAC,EAHW,cAAc,KAAd,cAAc,QAGzB","sourcesContent":["export type DeviceType =\n | 'vitre'\n | 'guest'\n | 'vitreMini'\n | 'vitrePrimary'\n | 'vitreSecondary'\n | 'tableau'\n | 'vitreGuest'\n | 'companion'\n\nexport type Privacy = 'none' | 'muted' | 'blurred' | 'mutedSender'\n\nexport type Language = 'fr' | 'en' | 'it'\n\n/// A signed-in companion user. `isAdministrator` is derived host-side from\n/// `roles.includes('administrator')` and surfaced as a boolean so apps can\n/// gate features without hard-coding the magic role string; `roles` is still\n/// available for fine-grained checks.\nexport type CompanionUser = {\n id: string\n firstName: string\n lastName: string\n roles: string[]\n isAdministrator: boolean\n}\n\n/// A companion's own identity and runtime context. Surfaced as\n/// `connector.companionInformation` (CompanionConnector) and\n/// `frame.companionInformation` (companion-side Frame / CompanionFrame).\n/// Strictly distinct from the Vitre identity (`hostInformation`).\n///\n/// `name` is the companion's chosen display name — a mandatory field on the\n/// connect page (account fullname, mobile device name, or manually entered,\n/// stored locally). It is also what the Vitre shows as this companion peer's\n/// name. `user` is present only when signed in (guest sessions omit it).\n/// `language` / `origin` / `version` describe the companion runtime, not the\n/// Vitre. Undefined on Vitre-side frames (a Vitre has no companion identity).\nexport type CompanionInformation = {\n /// Stable identifier for this companion as a participant (the signed-in\n /// user id, or a fallback for guest sessions). Distinct from the Vitre's\n /// `hostInformation.device.id`. Apps that render the companion as a\n /// collaboration peer (cursors, awareness) should key on this.\n id: string\n name: string\n /// The companion participant's colour (cursor / awareness). Distinct from\n /// the Vitre's `hostInformation.device.color`.\n color: string\n user?: CompanionUser\n language: Language\n origin: string\n version?: string\n}\n\n/**\n * @deprecated Use string\n */\nexport type LegacyI18nMap = {\n fr: string\n en: string\n it: string\n}\nexport type I18nMap = string | LegacyI18nMap\n\nexport type FileData = {\n id?: string\n name: string\n mime: string\n data: ArrayBufferLike\n shareTargetId?: string\n}\n\nexport type DeviceScalingVersion = 'legacy' | 'rotationIndependent'\n\nexport type Ratio = 'ratio16_9' | 'ratio9_16'\n\nexport type CropMode = 'cropped' | 'notCropped'\n\nexport type DeviceScaling = {\n scale: number\n offsetX: number\n offsetY: number\n orientation?: Orientation\n orientationBy?: OrientationBy\n ratio?: Ratio\n cropMode?: CropMode\n version?: DeviceScalingVersion\n}\n\nexport type DeviceFullscreen = 'fullscreen' | 'localDevice' | 'notFullscreen'\n\nexport type Device = {\n id: string\n name: string\n color: string\n type: DeviceType\n privacy: Privacy\n mainDeviceId?: string\n /**\n * represent the scaling applied on the local camera stream when sending to this device\n */\n sendingScaling?: DeviceScaling\n orientation?: Orientation\n orientationBy?: OrientationBy\n fullscreen?: DeviceFullscreen\n}\n\nexport type TeamInfo = {\n id: string\n name: string\n domain: string\n}\n\nexport type HostInformation = {\n language: Language\n device: Device\n version?: string\n devicesInSpace: Device[]\n spaceTeam: TeamInfo\n owner: TeamInfo\n origin: string\n team: string\n teamId: string\n space: Space\n color: string\n privacy: Privacy\n guestInviteUrl: string\n displays: Display[]\n settings?: any\n vitreSettings: VitreSettings\n companionCode?: string\n /**\n * `true` when the frame iframe is loaded by a la Vitre **companion**\n * (i.e. the host is `lavitre-companion`, not a Vitre). Apps can use\n * this to pick the right SDK surface — `initializeCompanionFrame` /\n * `CompanionFrame` on the companion side, `initializeFrame` / `Frame`\n * on the Vitre side — and to branch UI / behaviour that genuinely\n * differs between the two contexts (e.g. show a \"Leave this frame\"\n * button on the companion that calls `closeOnCompanion()`, omit it on\n * the Vitre).\n *\n * Undefined / false on the Vitre side. Set by\n * `lavitre-companion/.../CompanionApps.State.fs:buildVitreLikeHostInformation`.\n * Backward-compat: old hosts simply omit the field, so apps that read\n * it as `?? false` keep working unchanged. Added 1.15.\n */\n isCompanion?: boolean\n}\n\nexport type SendMessageTo = {\n connectorId?: string\n deviceIds?: string[]\n message: string\n fileData?: FileData\n}\n\nexport type SendMessageToAll = {\n connectorId?: string\n message: string\n fileData?: FileData\n}\n\nexport type SendKnockKnock = {\n deviceIds?: string[]\n}\n\nexport type DeviceJoined = {\n device: Device\n}\n\nexport type DeviceLeft = {\n deviceId: string\n}\n\nexport type DeviceMessageReceived = {\n from: string\n message: string\n fileData?: FileData\n fromConnectorId?: string\n}\n\nexport type MenuCategory = {\n label: string\n description?: string\n order?: number\n}\n\nexport type NumberRange = {\n id: string\n min: number\n max: number\n value: number\n step: number\n}\n\nexport type Field = { type: 'numberRange' } & NumberRange\n\nexport type Availability = {\n vitre?: boolean\n companion?: boolean\n companionAdmin?: boolean\n}\n\n/**\n * Declares that clicking a MenuEntry on the companion opens a frame on\n * the companion side (and on the Vitre too, if `kind === 'normal'`).\n *\n * `kind === 'local'` — the frame lives only on the companion that opened\n * it; its lifecycle is independent of any frame on the Vitre.\n *\n * `kind === 'normal'` — the frame on the companion is paired with a\n * frame on the Vitre via the same `frameConnectorId`. Per-frame messages\n * and yjs CRDT updates flow between them transparently.\n */\nexport type CompanionFrameTarget = {\n kind: 'local' | 'normal'\n frameConnectorId: string\n options: Omit<OpenFrameOptions, 'frameConnectorId'>\n}\n\nexport type EntryType = 'button' | 'toggle' | 'companionOpenLink'\n\nexport type OverlayIcon = {\n iconUrl?: string\n iconUrlChecked?: string\n iconUrlUnchecked?: string\n}\n\nexport type MenuEntry = {\n label: string\n id: string\n tag?: any\n order?: number\n hasConfirm?: boolean\n isChecked?: boolean\n isDisabled?: boolean\n category?: MenuCategory\n maskIconUrl?: string\n iconUrl?: string\n maskIconUrlChecked?: string\n iconUrlChecked?: string\n overlayIcons?: OverlayIcon[]\n menu?: MenuEntry[]\n description?: string\n isCloseOnClick?: boolean\n type?: EntryType\n focus?: boolean\n field?: Field\n linkUrl?: string\n radioGroup?: string\n availability?: Availability\n /**\n * If set, the host opens a companion frame when this entry is clicked\n * on the companion. The connector does not have to react to the\n * `menuClicked` event for this case — the frame opens automatically.\n *\n * Only honored when `availability.companion === true`.\n */\n opensCompanionFrame?: CompanionFrameTarget\n}\n\nexport type Size = {\n width: number\n height: number\n}\n\nexport type Rect = {\n x: number\n y: number\n width: number\n height: number\n}\n\nexport type Display = {\n bounds: Rect\n}\n\nexport type MonitorReference =\n | { type: 'contentMonitor' }\n | { type: 'monitorIndex'; index: number }\n\nexport type LayoutPosition = {\n /**\n * @deprecated Use left\n */\n x?: string\n /**\n * @deprecated Use top\n */\n y?: string\n width?: string\n height?: string\n left?: string\n top?: string\n right?: string\n bottom?: string\n centerX?: string\n centerY?: string\n monitor?: MonitorReference\n isFullscreen?: boolean\n}\n\nexport type DeviceRule = { deviceType?: DeviceType }\n\nexport type LayoutPositionRule = { type: 'deviceRule' } & DeviceRule\n\nexport type LayoutPositionWithRules = {\n width?: string\n height?: string\n left?: string\n top?: string\n right?: string\n bottom?: string\n centerX?: string\n centerY?: string\n monitor?: MonitorReference\n isFullscreen?: boolean\n rules?: LayoutPositionRule[]\n}\n\nexport type ViewMode = 'frame' | 'overlay'\n\nexport type FramePrivacy = 'shared' | 'pinned' | 'local'\n\n/**\n * Audience filter for the companion-frame open-on-companion behaviour. See\n * `CompanionFrameOption`. `'all'` means every connected companion is\n * targeted; `'administrator'` means only companions whose authenticated\n * user has the `administrator` role.\n */\nexport type CompanionFrameAudience = 'all' | 'administrator'\n\n/**\n * Declares how an opened frame should surface on connected companions. Lives\n * on `OpenFrameOptions` so the behaviour is decided per `connector.openFrame`\n * call. Companion side honours this at `FrameOpenedByVitre` reception time\n * (see `CompanionApps.State.fs`):\n *\n * - `autoOpen`: when set and the audience matches, the companion\n * auto-navigates to the new frame full-page IF it is\n * currently on the main Vitre page. If it is busy\n * (already on a frame, camera-share, etc.) the\n * auto-open is suppressed and a menu entry is added\n * to the CURRENT page's options instead. Auto-open\n * never preempts a busy companion.\n *\n * - `menuVisibility`: when set, a menu entry is added on the companion\n * side (in the current frame's options menu) for the\n * target audience, regardless of `autoOpen`. The\n * entry, when clicked, navigates to the frame.\n *\n * - `url`: REQUIRED. The URL the companion loads in its own\n * paired iframe. This is intentionally separate from\n * the Vitre frame's `OpenFrameOptions.url` so the\n * companion can present a different UI (and load its\n * own companion-frame entry point, e.g.\n * `companionFrame.html` initialised with\n * `initializeCompanionFrame`). The companion frame is\n * paired with the Vitre frame by the same\n * `frameConnectorId`, so per-frame messages and yjs\n * CRDT updates still flow between them.\n *\n * - `showBackButton`: controls the host's own \"back\" affordance on the\n * companion's full-page frame. The companion renders\n * the frame chrome-free (no la Vitre header) except a\n * single back button — the same control as the\n * camera-share page — that dismisses the frame. Set\n * `false` to hide it (e.g. when the app draws its own\n * close UI); the user can still leave via the device /\n * browser back gesture. Defaults to `true` (shown).\n *\n * - `edgeToEdge`: lets the frame cover the companion's whole surface,\n * system bars included; the app then keeps its controls\n * clear of them with `frame.safeAreaInsets`. See the\n * field doc.\n *\n * `url` is mandatory; `autoOpen` / `menuVisibility` / `showBackButton` /\n * `edgeToEdge` are independent and may be set together. If `autoOpen` and `menuVisibility`\n * are both absent the companion mounts nothing — no navigation, no menu —\n * and only the Vitre-side frame is shown.\n */\n/**\n * Subset of `MenuEntry` used to customise the companion menu entry that\n * (re)opens this companion frame — the entry surfaced when an `autoOpen` is\n * suppressed because the companion was busy, or added via `menuVisibility`.\n * Only the fields relevant to a host-driven open are exposed; the entry's\n * `id` and click behaviour are owned by the host. Any field left unset falls\n * back to the frame's `name` (label), no icon, and default ordering.\n */\nexport type CompanionFrameOpenMenuEntry = Pick<\n MenuEntry,\n 'label' | 'maskIconUrl' | 'iconUrl' | 'category' | 'description' | 'order'\n>\n\nexport type CompanionFrameOption = {\n url: string\n autoOpen?: CompanionFrameAudience\n menuVisibility?: CompanionFrameAudience\n /**\n * @deprecated Renamed to `showCloseButton`. Still honoured for backward\n * compatibility, but `showCloseButton` takes precedence when both are set.\n */\n showBackButton?: boolean\n /**\n * Whether the full-page companion frame shows the host's close button (the\n * control that dismisses the frame). Defaults to `true` when unset. Renamed\n * from the deprecated `showBackButton`.\n */\n showCloseButton?: boolean\n /**\n * Customises the companion menu entry that (re)opens this frame — the\n * busy-`autoOpen` fallback entry or the `menuVisibility` entry. Omit to\n * label the entry with the frame's `name` (no icon / category).\n */\n openMenuEntry?: CompanionFrameOpenMenuEntry\n /**\n * Whether the full-page companion frame covers the companion's whole\n * surface, system bars included (Android edge-to-edge: the navigation bar\n * is drawn translucent over the content). Set `true` only when the app\n * shifts its own controls with `frame.safeAreaInsets` — or with the\n * `--lavitre-safe-area-inset-*` CSS variables the SDK sets from it. When\n * unset or `false` the host keeps the iframe clear of the bars itself, so\n * a frame that knows nothing about insets is never covered. Added 1.51.\n */\n edgeToEdge?: boolean\n}\n\nexport type PositionType = 'Local' | 'Synced'\n\nexport type Interaction = 'notAllowed' | 'autoActiveOnFullscreen' | 'allowed'\n\nexport type BorderMode = 'borderLess' | 'border'\n\nexport type BorderOptions = {\n mode: BorderMode\n showToggleInMenu?: boolean\n}\n\nexport type StreamCapture = {\n data: ArrayBufferLike\n}\n\nexport type VoiceAction = {\n id: string\n message: I18nMap\n}\n\nexport type VoiceActionDetection = {\n id: string\n message: string\n language: string\n confidence: number\n}\n\nexport type OpenFrameOptions = {\n frameConnectorId: string\n streamId?: string\n name: string\n url: string\n size?: Size\n minSize?: Size\n maxSize?: Size\n startPosition?: LayoutPosition\n startPositions?: LayoutPositionWithRules[]\n /**\n * @deprecated Use startPosition.isFullscreen\n */\n startMode?: FrameStartMode\n /**\n * @deprecated Use interaction property\n */\n touchMode?: FrameTouchMode\n interaction?: Interaction\n allowFullscreen?: boolean\n menuVisibility?: MenuVisibility\n /**\n * @deprecated Use menuVisibility property vitre v20\n */\n hideMenu?: boolean\n startInteractive?: boolean\n resizeMode?: ResizeMode\n border?: BorderOptions\n data?: any\n file?: FileData\n mode?: ViewMode\n privacy?: FramePrivacy\n positionType?: PositionType\n voiceActions?: VoiceAction[]\n state?: Record<string, any>\n visibility?: Visibility\n closable?: boolean\n closeLabel?: string\n /**\n * Optional declaration of how this frame should surface on connected\n * companions. See `CompanionFrameOption`. When omitted the companion\n * side ignores the open (no auto-navigation, no menu) — the same\n * behaviour pre-1.13.\n */\n companionFrame?: CompanionFrameOption\n /**\n * Optional id of the device (see `HostInformation.devicesInSpace[].id`)\n * that should *own* the shared frame. The owner drives the languette\n * colour and, when it is a Vitre, takes over hosting the frame so it\n * survives the opener disconnecting (ownership transfer). When omitted\n * the opener owns the frame, as before. Change it afterwards with\n * `connector.setFrameOwner(frameConnectorId, owner)`.\n */\n owner?: string\n /**\n * SDK 1.32 — when `true`, the `file` is delivered ONLY to the opening\n * Vitre. The frame still opens and syncs on other peers, but the file\n * bytes are not propagated and the remote frames open without it. The\n * `data` field keeps syncing normally. The host strips the file before\n * cross-vitre sync — this is purely sender-side, so no peer-version gate\n * is needed (older receivers simply get a frame with no file, a state\n * they already handle). Has no effect when no `file` is provided.\n */\n localFile?: boolean\n /**\n * Icon shown for this frame's shared content on connected companions. A\n * bitmap (full colour). May be a path relative to the connector URL — the\n * host resolves it to an absolute URL. When both `iconUrl` and `maskIconUrl`\n * are set the companion prefers `maskIconUrl`. When neither is set the\n * companion falls back to the app icon (`ConnectorOptions.iconUrl`).\n */\n iconUrl?: string\n /**\n * Monochrome mask icon for this frame's shared content, tinted by the\n * companion theme (CSS `mask`). May be relative to the connector URL —\n * resolved absolute by the host. Preferred over `iconUrl` when both are set.\n */\n maskIconUrl?: string\n /**\n * CSS background applied to this frame's shared-content surface on the\n * Vitre (and on peer Vitres / tableaux showing it). Any CSS `background`\n * value — a colour, gradient, or `url(...)`. When set it overrides the\n * default surface background (`.lavitre-shared-object-content`, normally\n * black). Not resolved against the connector URL: pass an absolute URL if\n * you reference an image. When omitted the default background is kept.\n */\n background?: string\n /**\n * CSS `box-shadow` applied to this frame's shared-content surface on the\n * Vitre (and on peer Vitres / tableaux showing it). When set it overrides\n * the default surface shadow (`.lavitre-shared-object-content`). Pass\n * `'none'` to remove the shadow. When omitted the default shadow is kept.\n */\n boxShadow?: string\n /**\n * CSS `drop-shadow` filter applied to this frame's shared-content surface on\n * the Vitre (and on peer Vitres / tableaux showing it). The value is the\n * argument of the CSS `drop-shadow()` filter function — e.g.\n * `'0 4px 8px rgba(0,0,0,.5)'` — which the host wraps as\n * `filter: drop-shadow(<value>)`. Unlike `boxShadow` it follows the rendered\n * alpha shape, so it casts a shadow around non-rectangular / transparent\n * content (pair it with a transparent `background`). Pass `'none'` to remove\n * any filter. When omitted no drop-shadow filter is applied.\n */\n dropShadow?: string\n /**\n * CSS `backdrop-filter: blur(...)` applied to this frame's shared-content\n * surface on the Vitre (and on peer Vitres / tableaux showing it). The value\n * is the argument of the CSS `blur()` function — e.g. `'8px'` — which the\n * host wraps as `backdrop-filter: blur(<value>)`. It blurs whatever is\n * *behind* the surface (frosted-glass effect), so pair it with a translucent\n * `background`. Pass `'none'` to remove the backdrop filter. When omitted no\n * backdrop blur is applied.\n */\n backdropBlur?: string\n /**\n * Name to report for this frame in usage analytics (\"insights\"), instead of\n * the app's own name. A single app can open several kinds of frames — e.g.\n * Carbone opens \"Page blanche\", \"PDF\", \"Image\" — and by default every frame\n * is recorded under the app name (\"Carbone\"). Set `insightsName` per open to\n * distinguish them in the stats. When omitted the analytics fall back to the\n * current behaviour (the app name, then the frame `name`). Purely a reporting\n * label — it does not affect the frame UI (`name` still drives the visible\n * label) and never reaches other peers.\n */\n insightsName?: string\n}\n\n/**\n * Visual style of a frame's shared-content surface and its companion icon,\n * settable at open time (subset of `OpenFrameOptions`) and updatable at any\n * time with `connector.setChromeStyle(frameConnectorId, style)`. Every field\n * is optional: a field left `undefined` keeps the current value; pass an empty\n * string to clear an override back to the host default (e.g. `background: ''`).\n */\nexport type ChromeStyle = {\n /** See `OpenFrameOptions.background`. */\n background?: string\n /** See `OpenFrameOptions.boxShadow`. */\n boxShadow?: string\n /** See `OpenFrameOptions.dropShadow`. */\n dropShadow?: string\n /** See `OpenFrameOptions.backdropBlur`. */\n backdropBlur?: string\n /** See `OpenFrameOptions.iconUrl` (companion icon, bitmap). */\n iconUrl?: string\n /** See `OpenFrameOptions.maskIconUrl` (companion icon, monochrome mask). */\n maskIconUrl?: string\n}\n\n/**\n * @deprecated Use interaction property\n */\nexport enum FrameTouchMode {\n // Host will only allow manipulations. Touch events will not be forwarded to the webview\n ReadOnly = 'readonly',\n FullscreenOnly = 'fullscreenOnly',\n // Host will show a toggle button for interacting with the webview\n HostButtonInOut = 'hostButtonInOut',\n HostButtonMinimizeOnFullscreen = 'hostButtonMinimizeOnFullscreen',\n}\n\n/**\n * @deprecated Use startPosition.isFullscreen\n */\nexport enum FrameStartMode {\n Window = 'window',\n Fullscreen = 'fullscreen',\n}\n\nexport type ResizeMode =\n /**\n * @deprecated The method should not be used\n */\n | 'scale'\n /**\n * @deprecated The method should not be used\n */\n | 'resize'\n /**\n * @deprecated The method should not be used\n */\n | 'resizeAndKeepRatio'\n | 'no'\n | 'uniformRenderTransform'\n | 'freeRenderTransform'\n | 'uniformResize'\n | 'freeResize'\n\nexport type VideoContentHint = 'motion' | 'detail'\n\nexport type MenuClicked = {\n menuId: string\n isChecked: boolean\n tag: any | undefined\n}\n\nexport type LoadedFrame = {\n src: string\n name: string\n frameConnectorId: string\n}\n\nexport type LocalConnectorMessageReceived = {\n data: any\n fileData?: FileData\n from?: string\n}\n\nexport type SendToLocalFrame = {\n frameConnectorId?: string\n data: any\n fileData?: FileData\n}\n\nexport type EnumerateLoadedFramesCompleted = {\n requestId: string\n frames: LoadedFrame[]\n}\n\nexport type EnumerateLoadedFrames = {\n requestId: string\n}\n\nexport type PrivacyChanged = {\n privacy: Privacy\n}\n\nexport type MessageTargetCompanion = {\n type: 'companion'\n companionConnectionId: string\n}\n\nexport type MessageTarget = MessageTargetCompanion\n\n/**\n * A peer (Vitre or companion) that currently has a given frame open on\n * its side. Identified by the host's connection id so apps can address\n * it individually with the per-peer messaging APIs.\n */\nexport type FramePeer = {\n peerId: string\n deviceType: DeviceType\n name?: string\n}\n\n/**\n * Companion frame peer-presence wire events.\n *\n * `CompanionFramePeersUpdated` is the authoritative full snapshot — it\n * carries the complete current peer set and fires on every change.\n * `CompanionFramePeerJoined` / `CompanionFramePeerLeft` are convenience\n * incremental events derived from the same stream. Consumers should\n * subscribe to ONE model (snapshot OR incremental pair), not both, to\n * avoid double-counting every transition.\n */\nexport type CompanionFramePeerJoined = {\n peer: FramePeer\n}\n\nexport type CompanionFramePeerLeft = {\n peerId: string\n}\n\nexport type CompanionFramePeersUpdated = {\n peers: FramePeer[]\n}\n\nexport type AppMessage = {\n data: any\n fileData?: FileData\n target?: MessageTarget\n}\n\nexport type CameraExposureValue = {\n type: 'manual'\n exposure: number\n compensation: number\n}\n\nexport type CameraExposureAuto = {\n type: 'auto'\n}\n\nexport type CameraSettings = {\n exposure: CameraExposureAuto | CameraExposureValue\n deviceId?: string\n deviceName?: string\n}\n\nexport type StreamUsage = 'mainStream' | 'sharedStream'\n\nexport type Orientation = 'left' | 'right' | 'top' | 'bottom'\nexport type OrientationBy = 'system' | 'emulated'\n\nexport type ConnectedMediaDevice = {\n deviceId: string\n groupId: string\n kind: MediaDeviceKind\n label: string\n inUseBy: StreamUsage[]\n orientation?: Orientation\n orientationBySystem?: boolean\n}\n\nexport type AuthenticationMode = 'open' | 'userAccount'\n\nexport type SecuritySettings = {\n authentication: AuthenticationMode\n}\n\nexport type GuestSpace = {\n type: 'guestSpace'\n space: string\n teamDomain: string\n label: string\n}\n\nexport type TeamSpace = {\n type: 'teamSpace'\n space: string\n}\n\nexport type Space = GuestSpace | TeamSpace\n\n/**\n * Snapshot of the current active preset's noise filter selection.\n *\n * `active` and entries in `available` are the string ids of the F#\n * `Settings.Audio.AudioFilterLevel` enum. The current set is:\n *\n * \"none\" | \"rnnoise\" | \"rnnoise2\" | \"speex\" | \"noisegate\" | \"deepfilternet3\"\n *\n * Apps should treat the list as open — newer la Vitre builds may surface\n * additional filter ids the app doesn't know about. Render unknown ids\n * gracefully (e.g. as a generic option) rather than asserting on the set.\n */\nexport type AudioFilterView = {\n active: string\n available: string[]\n}\n\n/**\n * User-editable subset of the voice-profile chain (the \"custom\" profile).\n * Only meaningful when the active profile is \"custom\"; for the four frozen\n * profiles an app shows their fixed values read-only from its own table.\n */\nexport type CustomVoiceProfileView = {\n /** EQ presence (clarity) gain, dB. */\n presenceDb: number\n /** Compressor threshold, dB. */\n compThresholdDb: number\n /** Compressor ratio, >= 1. */\n compRatio: number\n /** De-esser sibilance cut, dB (negative). */\n deEsserCutDb: number\n}\n\nexport type CustomVoiceProfileSettingsSetter = {\n presenceDb?: number\n compThresholdDb?: number\n compRatio?: number\n deEsserCutDb?: number\n}\n\n/**\n * Voice profile (EQ + compressor + de-esser preset) applied for every\n * filter — including `none`. Ids:\n *\n * \"naturel\" | \"broadcast\" | \"douce\" | \"antifatigue\" | \"custom\"\n */\nexport type VoiceProfileView = {\n active: string\n available: string[]\n /** Persisted custom params (always present; edited only when\n * `active === 'custom'`). */\n custom: CustomVoiceProfileView\n}\n\n/**\n * DeepFilterNet 3 live-tunable knobs.\n *\n * `inputGainDb` and `wetDryMix` exist server-side but are intentionally\n * NOT exposed to apps — the SDK contract only covers the noise-reduction\n * tuning knobs that make sense in a \"voice quality\" UI.\n */\nexport type Dfn3View = {\n /** Suppression cap, 0..100 dB. Higher = more aggressive denoising. */\n attenLimDb: number\n /** Post-filter strength, 0..0.1. 0 disables it. */\n postFilterBeta: number\n}\n\nexport type Dfn3SettingsSetter = {\n attenLimDb?: number\n postFilterBeta?: number\n}\n\nexport type AudioSettings = {\n volume: number\n isMuted: boolean\n selectedPreset: string\n audioPresets: string[]\n /**\n * The following three are optional on the wire — older la Vitre builds\n * don't emit them. When undefined, treat as \"feature not available on\n * this Vitre\" rather than as a default value.\n */\n filter?: AudioFilterView\n voiceProfile?: VoiceProfileView\n dfn3?: Dfn3View\n}\n\nexport type AudioSettingsSetter = {\n volume?: number\n isMuted?: boolean\n selectedPreset?: string\n /**\n * Use one of `AudioFilterView.available` ids — unknown values are\n * silently dropped host-side rather than crashing the audio pipeline.\n */\n filter?: string\n voiceProfile?: string\n /**\n * Partial setter — only the fields present in the object are written.\n * Existing DFN3 properties not listed here (including `inputGainDb`\n * and `wetDryMix` which apps cannot manipulate) are preserved.\n */\n dfn3?: Dfn3SettingsSetter\n /**\n * Partial setter for the \"custom\" voice profile knobs. Only applied\n * when the active voice profile is \"custom\"; persisted regardless.\n */\n customVoiceProfile?: CustomVoiceProfileSettingsSetter\n}\n\nexport type VitreSettings = {\n availableMediaDevices: ConnectedMediaDevice[]\n audioSettings: AudioSettings\n cameraSettings: CameraSettings\n security: SecuritySettings\n spaces: Space[]\n currentSpace: Space\n language: Language\n color: string\n name?: string\n}\n\nexport type VitreSettingsSetter = {\n cameraSettings?: CameraSettings\n audioSettings?: AudioSettingsSetter\n}\n\nexport type DeviceTarget = 'all' | 'single'\n\nexport type KnockKnock = {\n from: Device\n target: DeviceTarget\n}\n\nexport type AppId = string\n\nexport type ShareFileRequest = {\n fileData: FileData\n targetAppId?: AppId\n /** SDK 1.20 — explicit owner device id for the resulting share. */\n owner?: string\n}\n\nexport type ShareDataRequest = {\n url: string\n targetAppId?: AppId\n /** SDK 1.20 — explicit owner device id for the resulting share. */\n owner?: string\n}\n\nexport type SaveSettings = {\n settings: any\n}\n\nexport type SettingsUpdated = {\n settings: any\n}\n\n/**\n * SDK 1.52 — the three levels of the AppSettings API (`Connector.getSettings`\n * / `setSettings`, `Frame.getSettings` / `setSettings`):\n * - `vitre` — this vitre only.\n * - `team` — the vitre's team, shared by every vitre/app instance in it.\n * - `space` — the space the vitre is currently in.\n *\n * Distinct from the legacy per-app `settingsSchema`/`saveSettings`/\n * `onSettingsUpdated` mechanism (a single, vitre-scoped JSON blob rendered by\n * the host's settings form) — the AppSettings API is app-driven, versioned,\n * and readable/writable at any of the three levels.\n */\nexport type AppSettingsLevel = 'vitre' | 'team' | 'space'\n\n/**\n * A JSON object of app settings at one `level`, with the optimistic-\n * concurrency `version` it was read/written at. `version` is `0` when the\n * level was never written. Max 64 KB serialized. Never store secrets —\n * every vitre/app instance of the team can read it.\n */\nexport type AppSettingsValue = {\n level: AppSettingsLevel\n value: Record<string, unknown>\n version: number\n}\n\n/** App → host: read the app's settings at `level`. Answered by `AppSettingsResponse`. */\nexport type GetAppSettings = {\n requestId: string\n level: AppSettingsLevel\n}\n\n/**\n * App → host: write the app's settings at `level`. `expectedVersion` must be\n * the version last observed for that level (via `AppSettingsResponse` or\n * `AppSettingsChanged`) — `0` if never written. A stale `expectedVersion`\n * fails with `AppSettingsResponse.error === 'conflict'`.\n */\nexport type SetAppSettings = {\n requestId: string\n level: AppSettingsLevel\n value: Record<string, unknown>\n expectedVersion: number\n}\n\n/** Host → app: reply to `GetAppSettings` / `SetAppSettings`, matched by `requestId`. */\nexport type AppSettingsResponse = {\n requestId: string\n level: AppSettingsLevel\n ok: boolean\n value?: Record<string, unknown>\n version?: number\n error?: 'conflict' | 'tooLarge' | 'invalid' | 'unavailable' | 'failed'\n}\n\n/**\n * Host → app: pushed whenever the settings at `level` change — including\n * changes this app itself made with `setSettings`, and changes made by\n * another vitre/app instance sharing the same team/space.\n */\nexport type AppSettingsChanged = AppSettingsValue\n\n/**\n * SDK 1.53 — scope for the public storage API (`Connector.publicStorage` /\n * `Frame.publicStorage`):\n * - `app` — this app's own space in the vitre's public storage.\n * - `shared` — a space all the team's apps share.\n *\n * Files in either scope go to the vitre's TEAM storage and are readable by\n * ANYONE without authentication at the returned `url` — never store private\n * data there. Only a Vitre-hosted app can write (a companion connector has\n * no `publicStorage`).\n */\nexport type PublicStorageScope = 'app' | 'shared'\n\n/**\n * App → host: upload (or overwrite) a file in public storage. Media and\n * documents only (images except SVG, video, audio, PDF, JSON, plain text,\n * CSV, Markdown, Office/OpenDocument); 50 MB max. Overwriting an existing\n * `path` replaces the file (readers revalidate). Answered by\n * `PublicStorageResponse`.\n *\n * `expiresIn` (SDK 1.54) is optional, in seconds — validated locally by the\n * SDK (`validateExpiresIn`) before this message is even sent. Omitted when\n * not requested; a host that predates this field ignores it. The vitre host\n * relays it to the server, which deletes the file once it elapses.\n */\nexport type PutPublicFile = {\n requestId: string\n scope: PublicStorageScope\n path: string\n contentType: string\n data: ArrayBuffer\n expiresIn?: number\n}\n\n/** App → host: delete a file from public storage. Answered by `PublicStorageResponse`. */\nexport type DeletePublicFile = {\n requestId: string\n scope: PublicStorageScope\n path: string\n}\n\n/**\n * App → host: list files in `scope`, optionally filtered to paths starting\n * with `prefix`. Answered by `PublicStorageResponse`.\n */\nexport type ListPublicFiles = {\n requestId: string\n scope: PublicStorageScope\n prefix?: string\n}\n\n/**\n * A file written to public storage. `url` is the stable, unauthenticated\n * link.\n *\n * `expiresAt` (SDK 1.54, ISO UTC) is present only when the file was\n * `put` with `expiresIn` — the link answers 404 and the server deletes the\n * file once this instant passes. Absent for a permanent file.\n *\n * `downloadUrl` (SDK 1.54) is `url` with `?download=1`, forcing a browser\n * download with the file's name instead of navigating to it — handy for a\n * QR code pointed at by a phone. The host may omit it (older hosts); when\n * absent the SDK fills it locally from `url` (see `withDownloadUrlFallback`),\n * so apps can always read `downloadUrl` regardless of host version.\n */\nexport type PublicFile = {\n path: string\n url: string\n size: number\n expiresAt?: string\n downloadUrl?: string\n}\n\n/** One entry returned by `listPublicFiles`. */\nexport type PublicFileEntry = PublicFile & {\n updatedAt?: string\n}\n\n/**\n * Host → app: reply to `PutPublicFile` / `DeletePublicFile` / `ListPublicFiles`,\n * matched by `requestId`. `file` answers a put, `files`/`baseUrl` answer a list.\n */\nexport type PublicStorageResponse = {\n requestId: string\n ok: boolean\n url?: string\n file?: PublicFile\n files?: PublicFileEntry[]\n baseUrl?: string\n error?:\n | 'tooLarge'\n | 'unsupportedType'\n | 'invalidPath'\n | 'storageNotConfigured'\n | 'unavailable'\n | 'failed'\n}\n\n/** Result of `publicStorage.list` — every app/vitre instance of the team sees the same files. */\nexport type PublicStorageListResult = {\n baseUrl: string\n files: PublicFileEntry[]\n}\n\n/**\n * SDK 1.56 — scope for the private storage API (`Connector.privateStorage`\n * / `Frame.privateStorage` / `CompanionConnector.privateStorage` /\n * `CompanionFrame.privateStorage`). Identical values to\n * `PublicStorageScope` — aliased rather than redefined.\n *\n * Unlike public storage, files in either scope have NO public link: they\n * are readable by any vitre or companion of the team (via `get` or a\n * temporary `getLink` signed link), never by an anonymous visitor. Only a\n * Vitre-hosted app can write (`put`/`delete`) — a companion connector/frame\n * only has `list`/`get`/`getLink`.\n */\nexport type PrivateStorageScope = PublicStorageScope\n\n/**\n * App → host: upload (or overwrite) a file in private storage. Any content\n * type is accepted — nothing here is ever served publicly as-is; 50 MB max.\n * Overwriting an existing `path` replaces the file (readers revalidate).\n * Vitre-only — the companion host answers with `error: 'unsupported'`.\n * Answered by `PrivateStorageResponse`.\n *\n * `expiresIn` is optional, in seconds — validated locally by the SDK\n * (`validatePrivateExpiresIn`) before this message is even sent. Omitted\n * when not requested, which keeps the file permanent.\n */\nexport type PutPrivateFile = {\n requestId: string\n scope: PrivateStorageScope\n path: string\n contentType: string\n data: ArrayBuffer\n expiresIn?: number\n}\n\n/**\n * App → host: delete a file from private storage. Resolves even if the\n * path didn't exist. Vitre-only — the companion host answers with\n * `error: 'unsupported'`. Answered by `PrivateStorageResponse`.\n */\nexport type DeletePrivateFile = {\n requestId: string\n scope: PrivateStorageScope\n path: string\n}\n\n/**\n * App → host: list files in `scope`, optionally filtered to paths starting\n * with `prefix`. Expired files are omitted. Answered by\n * `PrivateStorageResponse`.\n */\nexport type ListPrivateFiles = {\n requestId: string\n scope: PrivateStorageScope\n prefix?: string\n}\n\n/**\n * App → host: download the bytes of a private file. Answered by\n * `PrivateStorageResponse` (`data` + `contentType`), or\n * `error: 'notFound'` if the path doesn't exist or has expired.\n */\nexport type GetPrivateFile = {\n requestId: string\n scope: PrivateStorageScope\n path: string\n}\n\n/**\n * App → host: mint a temporary signed link to a private file — readable\n * without authentication for `expiresIn` seconds (host default 3600, max\n * 604800 — validated locally by the SDK, `validateLinkExpiresIn`), or until\n * the file itself is deleted/expires, whichever comes first. Answered by\n * `PrivateStorageResponse` (`link`), or `error: 'notFound'` if the path\n * doesn't exist or has expired.\n */\nexport type GetPrivateFileLink = {\n requestId: string\n scope: PrivateStorageScope\n path: string\n expiresIn?: number\n}\n\n/**\n * A file in private storage. Unlike `PublicFile` there is no stable `url` —\n * private files have no public link; use `getLink` for a temporary signed\n * one.\n *\n * `expiresAt` (ISO UTC) is present only when the file was `put` with\n * `expiresIn`. Absent for a permanent file.\n */\nexport type PrivateFile = {\n path: string\n size: number\n contentType: string\n updatedAt?: string\n expiresAt?: string\n}\n\n/**\n * A temporary signed link to a private file, from `getLink`. `url` opens\n * the file inline (when its content type is allowlisted) or downloads it;\n * `downloadUrl` is the same link forcing a download under the file's name\n * (`?download=1`), handy for a QR code. Dies at `expiresAt`, or earlier if\n * the underlying file is deleted or itself expires first.\n */\nexport type PrivateFileLink = {\n url: string\n downloadUrl: string\n expiresAt: string\n}\n\n/**\n * Host → app: reply to `PutPrivateFile` / `DeletePrivateFile` /\n * `ListPrivateFiles` / `GetPrivateFile` / `GetPrivateFileLink`, matched by\n * `requestId`. `file` answers a put, `files` answers a list, `data` +\n * `contentType` answer a get (`data` is an `ArrayBuffer`, transferred),\n * `link` answers a getLink.\n */\nexport type PrivateStorageResponse = {\n requestId: string\n ok: boolean\n file?: PrivateFile\n files?: PrivateFile[]\n data?: ArrayBuffer\n contentType?: string\n link?: PrivateFileLink\n error?: 'tooLarge' | 'invalidPath' | 'storageNotConfigured' | 'notFound' | 'unavailable' | 'failed'\n}\n\n/** Result of `privateStorage.list`. */\nexport type PrivateStorageListResult = {\n scope: PrivateStorageScope\n files: PrivateFile[]\n}\n\nexport type ChangeTeamSpace = {\n space: string\n}\n\nexport type ChangeTeamSpaceGuest = {\n space: string\n teamDomain: string\n}\n\nexport type NotificationButton = {\n id: string\n tag?: any\n iconUrl: string\n dismissOnClick?: boolean\n}\n\nexport type NotificationInfo = {\n id: string\n message: string\n iconUrl: string\n buttons?: NotificationButton[]\n closeTimeout?: number\n}\n\nexport type HideNotification = {\n id: string\n}\n\nexport type NotificationDismissed = {\n id: string\n}\n\nexport type NotificationButtonClicked = {\n id: string\n buttonId: string\n tag?: any\n}\n\nexport type DevicePrivacyChanged = { device: Device }\n\nexport type SDKInitRequest = {\n type: 'SDKInitRequest'\n version: string\n}\n\nexport type ChangePrivacy = {\n privacy: Privacy\n}\n\nexport type DeviceFrameReference = {\n frameConnectorId: string\n deviceId: string\n}\n\nexport type PendingDevicesInfo = {\n pendingDevices: Device[]\n}\n\nexport type EventTelemetry = {\n name: string\n properties?: Record<string, any>\n}\n\nexport type StartEventTelemetry = { name: string }\n\nexport type DeviceFullscreenUpdated = {\n deviceId: string\n fullscreen: DeviceFullscreen\n}\n\nexport type PositionUpdated = {\n position: Rect\n isFullscreen: boolean\n zIndex: number\n}\n\n/**\n * Distances, in CSS px of the frame's own viewport, from each edge of the\n * frame to the nearest edge of the area the host guarantees free of system\n * UI (Android navigation bar, display cutout, …). All zero unless the host\n * runs the frame edge-to-edge (`CompanionFrameOption.edgeToEdge`). Added 1.51.\n */\nexport type SafeAreaInsets = {\n top: number\n right: number\n bottom: number\n left: number\n}\n\nexport type SafeAreaInsetsUpdated = {\n safeAreaInsets: SafeAreaInsets\n}\n\nexport type Visibility = 'hidden' | 'visible' | 'visibleInFullscreenOnly'\nexport type MenuVisibility = 'hidden' | 'visible' | 'visibleInFullscreenOnly'\n\nexport type VisibilityChanged = {\n visibility: Visibility\n}\n\nexport type SetVisibility = { visibility: Visibility }\n\nexport type DeviceScalingUpdated = {\n deviceId: string\n sendingScaling: DeviceScaling\n orientation: Orientation\n orientationBy: OrientationBy\n}\n\nexport type UpdateStateEntry =\n | {\n action: 'add'\n key: string\n value: any\n }\n | {\n action: 'addOwned'\n key: string\n value: any\n }\n | {\n action: 'remove'\n key: string\n }\n\nexport type UpdatedStateEntry =\n | {\n action: 'add'\n key: string\n value: any\n }\n | {\n action: 'remove'\n key: string\n }\n | {\n action: 'addOwned'\n key: string\n value: any\n owner: string\n }\n\nexport type UpdateState = {\n updates: UpdateStateEntry[]\n}\n\nexport type ReplacedBy = 'local' | 'remote'\n\nexport type StateReplaced = {\n state: Record<string, any>\n delta: UpdatedStateEntry[]\n replacedBy: ReplacedBy\n}\n\nexport type GetStats = { requestId: string }\n\nexport type SetReducedAudioMode = { enabled: boolean }\n\nexport type DeviceTransceiverWebRTCStats = {\n deviceId: string\n transceiverId: string\n receiverStats?: any[]\n receiverStatsError?: string\n senderStats?: any[]\n senderStatsError?: string\n videoSendingParameters?: VideoSendingParameters\n /** Since 1.44: label of the outgoing track (originalTrack when the host wraps it). Absent on older hosts; explicit null on newer hosts when the transceiver has no sender track. */\n trackLabel?: string\n /** Since 1.44: sender track getSettings(), unwrapped via originalTrack when present. Absent on older hosts; null on newer hosts without a sender track. */\n trackSettings?: MediaTrackSettings\n /** Since 1.44: sender track getConstraints(). Absent on older hosts; null on newer hosts without a sender track. */\n trackConstraints?: MediaTrackConstraints\n /** Since 1.44: sender track muted flag. Absent on older hosts; null on newer hosts without a sender track. */\n trackMuted?: boolean\n /** Since 1.44: sender track enabled flag. Absent on older hosts; null on newer hosts without a sender track. */\n trackEnabled?: boolean\n /** Since 1.44: host sending parameters isEnabled (false under confidentiality). Absent on older hosts; null on newer hosts without a sender track. */\n sendingEnabled?: boolean\n}\n\nexport type MemoryInfo = {\n slotsInUse: number\n slots: number\n mbAvailable?: number\n}\n\nexport type VideoSendingParameters = {\n size?: Size\n bitrate?: number\n}\n\nexport type StatsResponse = {\n requestId: string\n webrtcStats: DeviceTransceiverWebRTCStats[]\n memory?: MemoryInfo\n cpuUsage?: number\n audioFilter?: string\n}\n\nexport type ConnectionCodeUpdated = {\n companionCode?: string\n}\n\nexport type FieldUpdated = {\n field: Field\n}\n\nexport type SendToSerialPort = {\n com: number\n baudRate: number\n readTimeout: number\n ackLineStartsWith?: string\n nackLineStartsWith?: string\n lines: string[]\n}\n\n/// Ask the host for access to a serial port. Resolves with the granted port\n/// name (empty string if denied/cancelled).\n/// - `port` given: the host pre-grants that port (so the next\n/// `navigator.serial.requestPort()` resolves to it silently) and resolves\n/// with `port`.\n/// - `port` omitted: the host shows its port-picker; resolves with the port\n/// the user chose (and pre-grants it).\n/// Honoured only when the app holds the WebSerial authorization.\nexport type RequestSerialPortAccess = {\n port?: string\n}\n\n/// Reply to RequestSerialPortAccess. On success `port` is the granted port\n/// name. On failure `port` is omitted and `reason` is one of the failure codes\n/// (the SDK rejects the promise with that reason).\nexport type SerialPortAccessReason = 'denied' | 'cancelled' | 'timeout'\nexport type SerialPortAccessResult = {\n port?: string\n reason?: SerialPortAccessReason\n}\n\nexport type StreamSizeUpdate = {\n deviceId: string\n size: Size\n}\n\nexport type RequestStreamSizeUpdate = {\n updates: StreamSizeUpdate[]\n}\n\nexport type DisconnectGuests = {\n deviceIds: string[]\n}\n\nexport type Characteristic = {\n uuid: string\n description: string\n properties: string\n}\n\nexport type OpenBTService = {\n serviceId: string\n requestId: string\n}\n\nexport type CloseBTService = {\n handleId: string\n}\n\nexport type WriteToCharacteristic = {\n handleId: string\n uuid: string\n buffer: ArrayBufferLike\n}\n\nexport type BluetoothFromApp =\n | ({ '@BluetoothFromApp': 'openBTService' } & OpenBTService)\n | ({ '@BluetoothFromApp': 'closeBTService' } & CloseBTService)\n | ({ '@BluetoothFromApp': 'writeToCharacteristic' } & WriteToCharacteristic)\n\nexport type OpenBTServiceResponseData = {\n requestId: string\n handleId: string\n characteristics: Characteristic[]\n}\n\nexport type OpenBTServiceResponse = {\n requestId: string\n isSuccess: boolean\n response?: OpenBTServiceResponseData\n error?: string\n}\n\nexport type BluetoothToApp = {\n '@BluetoothToApp': 'openBTServiceResponse'\n} & OpenBTServiceResponse\n"]}
@@ -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