@vantail/api 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +108 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# @vantail/api
|
|
2
|
+
|
|
3
|
+
The JavaScript SDK for [Vantail](https://github.com/Vantail/vantail): native
|
|
4
|
+
APIs for an application whose interface is a web page.
|
|
5
|
+
|
|
6
|
+
```bash
|
|
7
|
+
npm create @vantail my-app
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
Already have a project, this is installed for you by the scaffolder. Otherwise:
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
npm install @vantail/api
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## What it does
|
|
17
|
+
|
|
18
|
+
Your application is TypeScript and a web interface. This package is how it
|
|
19
|
+
reaches the things a browser cannot: the filesystem, native dialogs, the menu
|
|
20
|
+
bar, the tray, the clipboard, other processes, USB devices.
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
import { dialog, filesystem } from "@vantail/api";
|
|
24
|
+
|
|
25
|
+
const path = await dialog.openFile();
|
|
26
|
+
|
|
27
|
+
if (path) {
|
|
28
|
+
console.log(await filesystem.readText(path));
|
|
29
|
+
}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
There is no Node.js underneath. `node:fs` does not exist in a Vantail app and
|
|
33
|
+
neither does `require`; any browser-compatible npm package works, and this is
|
|
34
|
+
the replacement for the rest.
|
|
35
|
+
|
|
36
|
+
## What is in it
|
|
37
|
+
|
|
38
|
+
```text
|
|
39
|
+
app identity, lifecycle, and an event bus between windows
|
|
40
|
+
appWindow size, position, state, fullscreen, always-on-top, devtools
|
|
41
|
+
createWindow, getWindow, listWindows for more than one
|
|
42
|
+
|
|
43
|
+
filesystem read, write, copy, rename, watch - text and binary
|
|
44
|
+
dialog open, save, message, confirm - drawn by the OS
|
|
45
|
+
fileDrop files dragged onto the window, as real paths
|
|
46
|
+
clipboard text and images
|
|
47
|
+
|
|
48
|
+
menu the application menu, and context menus
|
|
49
|
+
tray an icon in the menu bar or system tray
|
|
50
|
+
notification a notification from the OS
|
|
51
|
+
shortcut key combinations claimed system-wide
|
|
52
|
+
autostart starting when the user logs in
|
|
53
|
+
power notices when the machine suspends and resumes
|
|
54
|
+
screen the monitors attached, in logical pixels
|
|
55
|
+
os platform, architecture, and per-application directories
|
|
56
|
+
|
|
57
|
+
process run another program, stream its output
|
|
58
|
+
shell hand a URL or file to whatever owns it
|
|
59
|
+
network HTTP from the runtime, past CORS
|
|
60
|
+
mdns discover services on the local network
|
|
61
|
+
hid talk to USB HID hardware
|
|
62
|
+
secrets the platform keychain
|
|
63
|
+
deepLink your own URL scheme
|
|
64
|
+
updater check, download, install, relaunch
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Everything returns a promise. Failures reject with a `VantailError` carrying a
|
|
68
|
+
stable `code`, which is what you branch on:
|
|
69
|
+
|
|
70
|
+
```ts
|
|
71
|
+
import { filesystem, VantailError } from "@vantail/api";
|
|
72
|
+
|
|
73
|
+
try {
|
|
74
|
+
await filesystem.readText("/etc/passwd");
|
|
75
|
+
} catch (error) {
|
|
76
|
+
if (VantailError.is(error, "PERMISSION_DENIED")) {
|
|
77
|
+
// ask the user to pick a file instead
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Nothing is available by default
|
|
83
|
+
|
|
84
|
+
Every native capability is denied until `vantail.config.ts` asks for it. A
|
|
85
|
+
webview that can read any file is a webview that can exfiltrate any file, so
|
|
86
|
+
the scope is something you write down:
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
permissions: {
|
|
90
|
+
dialog: true,
|
|
91
|
+
filesystem: {
|
|
92
|
+
read: ["$DOCUMENT/**"],
|
|
93
|
+
write: ["$APPDATA/**"],
|
|
94
|
+
},
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
A path the user picks in a dialog, or drops on the window, is granted for the
|
|
99
|
+
session on top of that - so the standing scope can stay narrow and
|
|
100
|
+
`dialog.openFile()` still opens anything they choose.
|
|
101
|
+
|
|
102
|
+
## Documentation
|
|
103
|
+
|
|
104
|
+
- [Every method, argument and return](https://github.com/Vantail/vantail/blob/main/docs/api.md)
|
|
105
|
+
- [The permission model in full](https://github.com/Vantail/vantail/blob/main/docs/permissions.md)
|
|
106
|
+
- [How a call reaches the OS and back](https://github.com/Vantail/vantail/blob/main/docs/architecture.md)
|
|
107
|
+
|
|
108
|
+
Zero dependencies. MIT licensed.
|