Solel//dev docs

Reference

Everything @solel-io/sdk exports, as it is in version 0.6.0. Most apps use the shared solel:

import { solel, SolelError, type AppContext } from '@solel-io/sdk';

Exports

Export What it is
solel The app's connection to . It's undefined where there's no window, such as while rendering on a server
createSolel(win?) Makes another connection, for tests and unusual hosts
SolelError What the calls throw or reject with when refuses or can't do something. Its message says why
Types AppContext, NoteInput, SolsDevice, Recording, Recorded, ReadyOptions, Theme, Layout, Role and Solel

setTitle, notify, openApp, close, record, solsDevice and solsChanged need ready() to have resolved first. Before then, they throw, or reject, with Call solel.ready() first.

ready(options?)

ready(options?: ReadyOptions): Promise<AppContext> connects to the desktop. Call it once when the app starts; later calls share the answer, and one that failed can be tried again. solel.context holds the answer once there is one.

Option Default What it does
applyTheme true Sets data-theme and color-scheme on <html> from the person's theme, and keeps them in step
timeout 5000 How many milliseconds to wait for the desktop before rejecting

It rejects straight away when the page isn't inside a frame, and after timeout when the desktop doesn't answer.

AppContext holds:

Field What it is
app install (this install's id, which notification links and the core's app endpoints use), id (from the manifest), name and version
user The person using the app: id, name, username and role (owner, admin, member, child or guest)
theme light or dark
layout desktop or phone
grants The grants approved for this install
path Where in the app it was opened, like /notes/7, or /
base The address the app's pages are served from, ending in /. Relative URLs resolve against it

on(event, listener)

Listens for a change, and returns a function that stops listening.

Event Value When
theme Theme The person switched between light and dark
layout Layout The desktop switched between desktop and phone
open string A notification link, or another app, opened this app at a path while it was running
solsDevice SolsDevice How Sols behave on this device changed. Only with sols.manage

setTitle(title)

Sets the window's title. The desktop shows up to 80 characters, and '' goes back to the app's name.

notify(note)

notify(note: NoteInput): Promise<{ sent: number }> sends the person using the app a notification, through the desktop. It needs the notify grant and reaches only that person. NoteInput has a title (needed), body, link (a path in the app, like /notes/7), level (info or warning) and key (one with the same key replaces a notification still waiting). See Notifications and badges for the limits.

openLink(url)

Opens a web page in a new tab, outside Solel. Relative addresses resolve against the page. Anything but http and https throws.

openApp(app, path?)

Opens another app the person has, by its manifest id, at a path that starts with /, as a notification link would: solel.openApp('io.solel.contacts', '/contact/<id>'). It needs no grant. An app that isn't installed, or is turned off, doesn't open, and the person is told so.

close()

Closes the app's window.

record()

record(): Promise<Recording> starts recording from the person's microphone, and resolves once it's listening. It needs the microphone grant. The desktop holds the microphone, since the frame can't, and the browser asks the person the first time, for Solel as a whole. It rejects when the person or their browser says no.

  • recording.stop() resolves with what was heard, as a Blob: audio/webm or audio/ogg with Opus where the browser can, otherwise audio/mp4.
  • recording.cancel() stops and throws it away.

A recording stops by itself after two minutes, when the app's window closes, and when the app starts another one. Calling stop() on one that has ended rejects.

solsDevice(change?) and solsChanged()

Both need the sols.manage grant. solsDevice resolves with how Sols behave on this device, { onTop, muted }: whether a Sol's floating face stays above other windows, and whether Sols neither listen nor speak here. Pass a change, like { muted: true }, to change it first. The desktop keeps both in the browser, for this device only.

solsChanged() tells the desktop a Sol was renamed, got a new face, or was added or removed, so the default Sol's name and face on the dock, the menu bar and its window follow at once.

gensDevice, gensChanged and the GensDevice type are the names these had before Sols were called Sols. They still work, but are deprecated.