heim 0.1.0-alpha.2 → 0.1.0-alpha.4
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/gen/compose.d.ts +2539 -2539
- package/package.json +12 -18
- package/tsconfig.json +27 -27
- package/types.d.ts +509 -294
- package/gen/heim.d.ts +0 -266
package/types.d.ts
CHANGED
|
@@ -1,294 +1,509 @@
|
|
|
1
|
-
import type {
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
*
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
/**
|
|
208
|
-
*
|
|
209
|
-
*/
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
1
|
+
import type { ComposeSpecification } from "./gen/compose";
|
|
2
|
+
|
|
3
|
+
declare global {
|
|
4
|
+
/**
|
|
5
|
+
* This is the main entry point for defining an application using the heim TypeScript library.
|
|
6
|
+
*/
|
|
7
|
+
function defineApp<const I extends Inputs = Record<string, never>>(
|
|
8
|
+
config: AppConfig<I>,
|
|
9
|
+
): AppConfig<I>;
|
|
10
|
+
|
|
11
|
+
// Types
|
|
12
|
+
type AppConfig<I extends Inputs = Record<string, never>> = {
|
|
13
|
+
/**
|
|
14
|
+
* The metadata is the descriptive information of the app such as its name, version, description, and other relevant information.
|
|
15
|
+
*/
|
|
16
|
+
metadata: Metadata;
|
|
17
|
+
/**
|
|
18
|
+
* The inputs declare the questions the user is asked during installation. Answers are stored and reused on later runs,
|
|
19
|
+
* so updates run unattended.
|
|
20
|
+
*/
|
|
21
|
+
inputs?: I;
|
|
22
|
+
/**
|
|
23
|
+
* The user interface configuration defines how the app's UI should be set up, including the services it provides, the ports it uses, and whether it requires authentication.
|
|
24
|
+
* It is optional, and if not provided, the app will only render the console as the user interface.
|
|
25
|
+
*/
|
|
26
|
+
ui?: UserInterface | ((ctx: UserInterfaceContext) => UserInterface);
|
|
27
|
+
/**
|
|
28
|
+
* The compose configuration defines the Docker Compose specification for the app, including the services, volumes, networks, and other Docker resources that the app requires to run.
|
|
29
|
+
*/
|
|
30
|
+
compose: Compose | ((ctx: ComposeContext<I>) => Compose);
|
|
31
|
+
/**
|
|
32
|
+
* The backup configuration defines which volumes of the app should be backed up. It also allows specifying a custom backup command.
|
|
33
|
+
*/
|
|
34
|
+
backup?: Backup | ((ctx: BackupContext) => Backup);
|
|
35
|
+
/**
|
|
36
|
+
* The restore configuration defines how to restore the app from a backup, including any custom restore commands that need to be executed before the restore process.
|
|
37
|
+
*/
|
|
38
|
+
restore?: (ctx: RestoreContext) => void;
|
|
39
|
+
};
|
|
40
|
+
|
|
41
|
+
type Metadata = {
|
|
42
|
+
/**
|
|
43
|
+
* Part of the id of the app. It needs to be unique within one namespace.
|
|
44
|
+
*/
|
|
45
|
+
slug: string;
|
|
46
|
+
/**
|
|
47
|
+
* The version of the app, must be a valid semver version.
|
|
48
|
+
*/
|
|
49
|
+
version: string;
|
|
50
|
+
/**
|
|
51
|
+
* Display name shown in the UI.
|
|
52
|
+
*/
|
|
53
|
+
title: LocalizedString | string;
|
|
54
|
+
/**
|
|
55
|
+
* A short description of the app.
|
|
56
|
+
*/
|
|
57
|
+
tagline: LocalizedString1 | string;
|
|
58
|
+
/**
|
|
59
|
+
* The description of the app. It needs to be a markdown file.
|
|
60
|
+
*/
|
|
61
|
+
readme?: LocalizedString2 | string;
|
|
62
|
+
/**
|
|
63
|
+
* The category of the app.
|
|
64
|
+
*/
|
|
65
|
+
category:
|
|
66
|
+
| "books"
|
|
67
|
+
| "medical"
|
|
68
|
+
| "business"
|
|
69
|
+
| "music"
|
|
70
|
+
| "developer-tools"
|
|
71
|
+
| "navigation"
|
|
72
|
+
| "education"
|
|
73
|
+
| "news"
|
|
74
|
+
| "entertainment"
|
|
75
|
+
| "photo-and-video"
|
|
76
|
+
| "finance"
|
|
77
|
+
| "productivity"
|
|
78
|
+
| "food-and-drink"
|
|
79
|
+
| "reference"
|
|
80
|
+
| "games"
|
|
81
|
+
| "graphics-and-design"
|
|
82
|
+
| "shopping"
|
|
83
|
+
| "health-and-fitness"
|
|
84
|
+
| "social-networking"
|
|
85
|
+
| "lifestyle"
|
|
86
|
+
| "sports"
|
|
87
|
+
| "kids"
|
|
88
|
+
| "travel"
|
|
89
|
+
| "magazines-and-newspapers"
|
|
90
|
+
| "utilities"
|
|
91
|
+
| "weather";
|
|
92
|
+
/**
|
|
93
|
+
* The developer (individual person or company) of the app. This is either you or the original developer of the software.
|
|
94
|
+
*/
|
|
95
|
+
developer: string;
|
|
96
|
+
/**
|
|
97
|
+
* The icon of the app. It needs to be an SVG file.
|
|
98
|
+
*/
|
|
99
|
+
icon?: string;
|
|
100
|
+
/**
|
|
101
|
+
* A list of images that showcase the app.
|
|
102
|
+
*/
|
|
103
|
+
galleryImages?: string[] | LocalizedString3;
|
|
104
|
+
/**
|
|
105
|
+
* The website of the app.
|
|
106
|
+
*/
|
|
107
|
+
website?: string;
|
|
108
|
+
/**
|
|
109
|
+
* The version control repository of the app (e.g. GitHub).
|
|
110
|
+
*/
|
|
111
|
+
repository?: string;
|
|
112
|
+
/**
|
|
113
|
+
* The support website of the app.
|
|
114
|
+
*/
|
|
115
|
+
support?: string;
|
|
116
|
+
/**
|
|
117
|
+
* The license file of the app.
|
|
118
|
+
*/
|
|
119
|
+
license?: LocalizedString4 | string;
|
|
120
|
+
/**
|
|
121
|
+
* The minimum version of heim that is required to run the app. This is used to prevent users from installing an app that requires features of a newer version of heim.
|
|
122
|
+
*/
|
|
123
|
+
minHeimVersion?: string;
|
|
124
|
+
};
|
|
125
|
+
|
|
126
|
+
type Inputs = Record<string, Input>;
|
|
127
|
+
|
|
128
|
+
type Input = TextInput | ConfirmInput | SelectInput | MultiselectInput;
|
|
129
|
+
|
|
130
|
+
type TextInput = {
|
|
131
|
+
type: "text";
|
|
132
|
+
/**
|
|
133
|
+
* The message to display to the user when prompting for input, e.g. "Enter your new username".
|
|
134
|
+
*/
|
|
135
|
+
message: string;
|
|
136
|
+
/**
|
|
137
|
+
* An optional default value to pre-fill the input field, e.g. "sharknoon".
|
|
138
|
+
*/
|
|
139
|
+
default?: string;
|
|
140
|
+
/**
|
|
141
|
+
* If true, the input will allow multiple lines to be entered. Default is false.
|
|
142
|
+
*/
|
|
143
|
+
multiLine?: boolean;
|
|
144
|
+
/**
|
|
145
|
+
* If set, the input will be masked with this character (e.g. for passwords).
|
|
146
|
+
*/
|
|
147
|
+
mask?: string;
|
|
148
|
+
};
|
|
149
|
+
|
|
150
|
+
type ConfirmInput = {
|
|
151
|
+
type: "confirm";
|
|
152
|
+
/**
|
|
153
|
+
* The message to display to the user when prompting for confirmation, e.g. "Do you want to enable feature X?".
|
|
154
|
+
*/
|
|
155
|
+
message: string;
|
|
156
|
+
/**
|
|
157
|
+
* An optional default value to pre-fill the confirmation, e.g. true (which would correspond to "Yes"). Default is false.
|
|
158
|
+
*/
|
|
159
|
+
default?: boolean;
|
|
160
|
+
/**
|
|
161
|
+
* The text to display for the confirmation, e.g. "Yes". Default is "Yes".
|
|
162
|
+
*/
|
|
163
|
+
confirmText?: string;
|
|
164
|
+
/**
|
|
165
|
+
* The text to display for the rejection, e.g. "No". Default is "No".
|
|
166
|
+
*/
|
|
167
|
+
rejectText?: string;
|
|
168
|
+
};
|
|
169
|
+
|
|
170
|
+
type InputOption = {
|
|
171
|
+
/**
|
|
172
|
+
* The value that is returned when the option is selected.
|
|
173
|
+
*/
|
|
174
|
+
value: string;
|
|
175
|
+
/**
|
|
176
|
+
* The label that is displayed to the user.
|
|
177
|
+
*/
|
|
178
|
+
label: string;
|
|
179
|
+
};
|
|
180
|
+
|
|
181
|
+
type SelectInput = {
|
|
182
|
+
type: "select";
|
|
183
|
+
/**
|
|
184
|
+
* The message to display to the user when prompting for selection, e.g. "Select your storage type".
|
|
185
|
+
*/
|
|
186
|
+
message: string;
|
|
187
|
+
/**
|
|
188
|
+
* A list of options to choose from. For example: [{ value: "hdd", label: "Hard Drive" }, { value: "ssd", label: "Solid State Drive" }].
|
|
189
|
+
*/
|
|
190
|
+
options: readonly InputOption[];
|
|
191
|
+
/**
|
|
192
|
+
* An optional default value to pre-select an option, e.g. "ssd". The default must match one of the values in the options array.
|
|
193
|
+
*/
|
|
194
|
+
default?: string;
|
|
195
|
+
};
|
|
196
|
+
|
|
197
|
+
type MultiselectInput = {
|
|
198
|
+
type: "multiselect";
|
|
199
|
+
/**
|
|
200
|
+
* The message to display to the user when prompting for selection, e.g. "Select the video encoding backends you want to use".
|
|
201
|
+
*/
|
|
202
|
+
message: string;
|
|
203
|
+
/**
|
|
204
|
+
* A list of options to choose from. For example: [{ value: "h264", label: "H.264" }, { value: "vp9", label: "VP9" }].
|
|
205
|
+
*/
|
|
206
|
+
options: readonly InputOption[];
|
|
207
|
+
/**
|
|
208
|
+
* An optional list of default values to pre-select options, e.g. ["h264", "vp9"]. The defaults must match the values in the options array.
|
|
209
|
+
*/
|
|
210
|
+
default?: readonly string[];
|
|
211
|
+
};
|
|
212
|
+
|
|
213
|
+
type InputValue<T extends Input> = T extends { type: "text" }
|
|
214
|
+
? string
|
|
215
|
+
: T extends { type: "confirm" }
|
|
216
|
+
? boolean
|
|
217
|
+
: T extends {
|
|
218
|
+
type: "select";
|
|
219
|
+
options: readonly {
|
|
220
|
+
value: infer V extends string;
|
|
221
|
+
label: string;
|
|
222
|
+
}[];
|
|
223
|
+
}
|
|
224
|
+
? V
|
|
225
|
+
: T extends {
|
|
226
|
+
type: "multiselect";
|
|
227
|
+
options: readonly {
|
|
228
|
+
value: infer V extends string;
|
|
229
|
+
label: string;
|
|
230
|
+
}[];
|
|
231
|
+
}
|
|
232
|
+
? V[]
|
|
233
|
+
: never;
|
|
234
|
+
|
|
235
|
+
type ValuesContext<I extends Inputs> = {
|
|
236
|
+
/**
|
|
237
|
+
* The resolved answers to the declared inputs. Answers are stored on installation and reused on later runs,
|
|
238
|
+
* so updates run unattended.
|
|
239
|
+
*/
|
|
240
|
+
values: { [K in keyof I]: InputValue<I[K]> };
|
|
241
|
+
};
|
|
242
|
+
|
|
243
|
+
type UserInterface = {
|
|
244
|
+
/**
|
|
245
|
+
* The name of the compose service that provides the user interface.
|
|
246
|
+
*/
|
|
247
|
+
service: string;
|
|
248
|
+
/**
|
|
249
|
+
* The port of the compose service that provides the user interface. Note that this port does NOT need to be exposed by the container runtime.
|
|
250
|
+
*/
|
|
251
|
+
port: number;
|
|
252
|
+
/**
|
|
253
|
+
* The url path of the compose service that provides the user interface.
|
|
254
|
+
*/
|
|
255
|
+
path?: string;
|
|
256
|
+
/**
|
|
257
|
+
* Whether the user interface of this app has an auth in front of it. Can be 'true' if the app itself provides an authentication mechanism or is intended to be public.
|
|
258
|
+
*/
|
|
259
|
+
hasAuth?: boolean;
|
|
260
|
+
};
|
|
261
|
+
type UserInterfaceContext = LogContext & ConfigContext;
|
|
262
|
+
|
|
263
|
+
type Compose = ComposeSpecification;
|
|
264
|
+
type ComposeContext<I extends Inputs = Record<string, never>> = LogContext &
|
|
265
|
+
DataContext &
|
|
266
|
+
ConfigContext &
|
|
267
|
+
SystemContext &
|
|
268
|
+
ValuesContext<I> &
|
|
269
|
+
CryptoContext;
|
|
270
|
+
|
|
271
|
+
type Backup = {
|
|
272
|
+
/**
|
|
273
|
+
* The volumes configuration defines which volumes of the app should be included or excluded in the backup. Each entry in the
|
|
274
|
+
* include list can be a volume name (string) to include the entire volume, or an object with a volume
|
|
275
|
+
* name and file filters to include or exclude only specific files within that volume.
|
|
276
|
+
*
|
|
277
|
+
* Only whole volumes can be excluded, not specific files within a volume. To exclude specific files, use the include list with file filters.
|
|
278
|
+
*
|
|
279
|
+
* If neither the include nor the exclude
|
|
280
|
+
* list is set, all volumes will be included in the backup. If both lists are set, only the volumes in the include list that
|
|
281
|
+
* are not in the exclude list will be included in the backup.
|
|
282
|
+
*/
|
|
283
|
+
volumes?: {
|
|
284
|
+
/**
|
|
285
|
+
* A list of volumes to include in the backup. Each entry can be a volume name (string) to include the entire volume,
|
|
286
|
+
* or an object with a volume name and file filters to include only specific files within that volume.
|
|
287
|
+
* If neither this list nor the exclude list is set, all volumes will be included.
|
|
288
|
+
* If both lists are set, only the volumes in the include list that are not in the exclude list will be included.
|
|
289
|
+
*/
|
|
290
|
+
include?: (string | VolumeFilter)[];
|
|
291
|
+
/**
|
|
292
|
+
* A list of volumes to exclude from the backup. Each entry is a volume name (string) to exclude the entire volume.
|
|
293
|
+
* If neither this list nor the include list is set, all volumes will be included.
|
|
294
|
+
* If both lists are set, only the volumes in the include list that are not in the exclude list will be included.
|
|
295
|
+
*/
|
|
296
|
+
exclude?: string[];
|
|
297
|
+
};
|
|
298
|
+
/**
|
|
299
|
+
* Additional data to include in the backup that is not part of any volume, such as database dumps.
|
|
300
|
+
* The key is the name of the artifact and the value is its content, either as text or as raw bytes.
|
|
301
|
+
* The name can be used in the restore process to get the artifact back.
|
|
302
|
+
*/
|
|
303
|
+
artifacts?: Record<string, string | ArrayLike<number>>;
|
|
304
|
+
};
|
|
305
|
+
type VolumeFilter = {
|
|
306
|
+
/**
|
|
307
|
+
* The name of the volume.
|
|
308
|
+
*/
|
|
309
|
+
name: string;
|
|
310
|
+
/**
|
|
311
|
+
* File path patterns (globs) to include within this volume.
|
|
312
|
+
* If neither this nor the exclude property is set, the entire volume will be included.
|
|
313
|
+
* If both include and exclude are set, only the files that match the include patterns and do not match the exclude patterns will be included.
|
|
314
|
+
*/
|
|
315
|
+
includePatterns?: string[];
|
|
316
|
+
/**
|
|
317
|
+
* File path patterns (globs) to exclude within this volume.
|
|
318
|
+
* If neither this nor the include property is set, the entire volume will be included.
|
|
319
|
+
* If both include and exclude are set, only the files that match the include patterns and do not match the exclude patterns will be included.
|
|
320
|
+
*/
|
|
321
|
+
excludePatterns?: string[];
|
|
322
|
+
};
|
|
323
|
+
type BackupContext = LogContext & ConfigContext & ContainerContext;
|
|
324
|
+
|
|
325
|
+
type RestoreContext = LogContext &
|
|
326
|
+
ConfigContext &
|
|
327
|
+
ContainerContext &
|
|
328
|
+
ArtifactsContext;
|
|
329
|
+
|
|
330
|
+
// General types
|
|
331
|
+
|
|
332
|
+
type LogContext = {
|
|
333
|
+
log: {
|
|
334
|
+
/**
|
|
335
|
+
* Logs an informational message to the user.
|
|
336
|
+
*/
|
|
337
|
+
info: (message: string) => void;
|
|
338
|
+
/**
|
|
339
|
+
* Logs a warning message to the user.
|
|
340
|
+
*/
|
|
341
|
+
warning: (message: string) => void;
|
|
342
|
+
/**
|
|
343
|
+
* Logs an error message to the user.
|
|
344
|
+
*/
|
|
345
|
+
error: (message: string) => void;
|
|
346
|
+
};
|
|
347
|
+
};
|
|
348
|
+
|
|
349
|
+
type DataContext = {
|
|
350
|
+
data: {
|
|
351
|
+
/**
|
|
352
|
+
* Returns the path to a directory that can be used for shared storage between apps.
|
|
353
|
+
*/
|
|
354
|
+
sharedStorageDir(): string;
|
|
355
|
+
};
|
|
356
|
+
};
|
|
357
|
+
|
|
358
|
+
type ReadOnlyConfigContext = {
|
|
359
|
+
config: {
|
|
360
|
+
/**
|
|
361
|
+
* Returns a previously stored configuration value for the given key. If the key does not exist, it returns null.
|
|
362
|
+
* @param key The key of the configuration item to retrieve.
|
|
363
|
+
*/
|
|
364
|
+
getItem(key: string): string | null;
|
|
365
|
+
/**
|
|
366
|
+
* Returns the number of configuration items stored.
|
|
367
|
+
*/
|
|
368
|
+
size(): number;
|
|
369
|
+
/**
|
|
370
|
+
* Returns the key of the configuration item at the given index. If the index is out of bounds, it returns null.
|
|
371
|
+
* @param index The index of the configuration item.
|
|
372
|
+
*/
|
|
373
|
+
key(index: number): string | null;
|
|
374
|
+
};
|
|
375
|
+
};
|
|
376
|
+
|
|
377
|
+
type WriteOnlyConfigContext = {
|
|
378
|
+
config: {
|
|
379
|
+
/**
|
|
380
|
+
* Stores a configuration value for the given key.
|
|
381
|
+
* @param key The key of the configuration item to store.
|
|
382
|
+
* @param value The value to store.
|
|
383
|
+
*/
|
|
384
|
+
setItem(key: string, value: string): void;
|
|
385
|
+
/**
|
|
386
|
+
* Removes a configuration value for the given key.
|
|
387
|
+
* @param key The key of the configuration item to remove.
|
|
388
|
+
*/
|
|
389
|
+
removeItem(key: string): void;
|
|
390
|
+
/**
|
|
391
|
+
* Removes all configuration items for this app.
|
|
392
|
+
*/
|
|
393
|
+
clear(): void;
|
|
394
|
+
};
|
|
395
|
+
};
|
|
396
|
+
|
|
397
|
+
type ConfigContext = ReadOnlyConfigContext & WriteOnlyConfigContext;
|
|
398
|
+
|
|
399
|
+
type SystemContext = {
|
|
400
|
+
system: {
|
|
401
|
+
/**
|
|
402
|
+
* Returns a list of common IANA timezones, e.g. ["Europe/Berlin", "America/New_York", ...].
|
|
403
|
+
*/
|
|
404
|
+
timezones(): string[];
|
|
405
|
+
/**
|
|
406
|
+
* Returns the system's current timezone in IANA format, e.g. "Europe/Berlin".
|
|
407
|
+
* This is determined by the host environment and can be overridden by the user.
|
|
408
|
+
* If no override is set and the host environment does not provide a timezone, it defaults to "UTC".
|
|
409
|
+
*/
|
|
410
|
+
timezone(): string;
|
|
411
|
+
};
|
|
412
|
+
};
|
|
413
|
+
|
|
414
|
+
type CryptoContext = {
|
|
415
|
+
crypto: {
|
|
416
|
+
/**
|
|
417
|
+
* Generates a random password with the specified options.
|
|
418
|
+
* @param opts Options for password generation
|
|
419
|
+
*/
|
|
420
|
+
password(opts?: {
|
|
421
|
+
/**
|
|
422
|
+
* The length of the generated password. Default is 16.
|
|
423
|
+
*/
|
|
424
|
+
length?: number;
|
|
425
|
+
/**
|
|
426
|
+
* Exclude numbers from the generated password. Default is false.
|
|
427
|
+
*/
|
|
428
|
+
excludeNumbers?: boolean;
|
|
429
|
+
/**
|
|
430
|
+
* Exclude special characters from the generated password. Default is false.
|
|
431
|
+
*/
|
|
432
|
+
excludeSpecial?: boolean;
|
|
433
|
+
}): string;
|
|
434
|
+
};
|
|
435
|
+
};
|
|
436
|
+
|
|
437
|
+
type ContainerContext = {
|
|
438
|
+
container: {
|
|
439
|
+
/**
|
|
440
|
+
* Executes a command in the container of a specific service. Uses docker compose exec under the hood.
|
|
441
|
+
*
|
|
442
|
+
* The output is decoded as UTF-8 text by default. Set the binary option to true
|
|
443
|
+
* to get the raw bytes instead, for example for binary database dumps.
|
|
444
|
+
*
|
|
445
|
+
* A non-zero exit code is reported in the result, not thrown as an error.
|
|
446
|
+
* An error is only thrown if the command could not be executed at all,
|
|
447
|
+
* for example when no running container exists for the service.
|
|
448
|
+
*/
|
|
449
|
+
exec: {
|
|
450
|
+
(
|
|
451
|
+
service: string,
|
|
452
|
+
command: string[],
|
|
453
|
+
options?: ExecOptions & { binary?: false },
|
|
454
|
+
): ExecResult<string>;
|
|
455
|
+
(
|
|
456
|
+
service: string,
|
|
457
|
+
command: string[],
|
|
458
|
+
options: ExecOptions & { binary: true },
|
|
459
|
+
): ExecResult<ArrayLike<number>>;
|
|
460
|
+
};
|
|
461
|
+
};
|
|
462
|
+
};
|
|
463
|
+
|
|
464
|
+
type ExecOptions = {
|
|
465
|
+
/**
|
|
466
|
+
* Data that is written to the standard input of the command.
|
|
467
|
+
*/
|
|
468
|
+
stdin?: string | ArrayLike<number>;
|
|
469
|
+
/**
|
|
470
|
+
* Return the output as raw bytes instead of UTF-8 text. Default is false.
|
|
471
|
+
*/
|
|
472
|
+
binary?: boolean;
|
|
473
|
+
};
|
|
474
|
+
|
|
475
|
+
type ExecResult<T = string> = {
|
|
476
|
+
/**
|
|
477
|
+
* The standard output of the command.
|
|
478
|
+
*/
|
|
479
|
+
stdout: T;
|
|
480
|
+
/**
|
|
481
|
+
* The standard error of the command.
|
|
482
|
+
*/
|
|
483
|
+
stderr: T;
|
|
484
|
+
/**
|
|
485
|
+
* The standard output and standard error combined, in the order they were written.
|
|
486
|
+
*/
|
|
487
|
+
output: T;
|
|
488
|
+
/**
|
|
489
|
+
* The exit code of the command. 0 means success.
|
|
490
|
+
*/
|
|
491
|
+
exitCode: number;
|
|
492
|
+
};
|
|
493
|
+
|
|
494
|
+
type ArtifactsContext = {
|
|
495
|
+
/**
|
|
496
|
+
* The artifacts that were created e.g. by the backup, such as database dumps.
|
|
497
|
+
*/
|
|
498
|
+
artifacts: {
|
|
499
|
+
/**
|
|
500
|
+
* Returns the artifact decoded as UTF-8 text, or null if it does not exist.
|
|
501
|
+
*/
|
|
502
|
+
get: (name: string) => string | null;
|
|
503
|
+
/**
|
|
504
|
+
* Returns the raw bytes of the artifact, or null if it does not exist.
|
|
505
|
+
*/
|
|
506
|
+
getBytes: (name: string) => ArrayLike<number> | null;
|
|
507
|
+
};
|
|
508
|
+
};
|
|
509
|
+
}
|