@moonbase.sh/gorilla-engine 0.0.0 → 0.2.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.
- package/README.md +77 -8
- package/dist/index.cjs +1866 -0
- package/dist/index.d.cts +322 -0
- package/dist/index.d.ts +322 -0
- package/dist/index.js +1821 -0
- package/dist/moonbase-gorilla-engine.js +801 -0
- package/package.json +57 -4
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,322 @@
|
|
|
1
|
+
import { ActivationStatus, ActivationUiOptions, ActivationControllerOptions, ActivationScreen, ActivationController, ActivationState } from '@moonbase.sh/licensing';
|
|
2
|
+
export { ActivationError, ActivationErrorKind, ActivationLogger, ActivationScreen, ActivationState, ActivationStatus, ActivationStrings, ActivationUiOptions, LicenseView, LockReason, MoonbaseError, ReleaseNotCoveredError, TrialFeature } from '@moonbase.sh/licensing';
|
|
3
|
+
import { ReactElement } from 'react';
|
|
4
|
+
|
|
5
|
+
/** How the update download is going, as the update screen shows it. */
|
|
6
|
+
interface DownloadState {
|
|
7
|
+
phase: 'idle' | 'downloading' | 'done' | 'failed' | 'notCovered';
|
|
8
|
+
progress: number | null;
|
|
9
|
+
path: string | null;
|
|
10
|
+
error: string | null;
|
|
11
|
+
/** For `notCovered`: what the customer's licenses cover, and where to upgrade. */
|
|
12
|
+
releaseAccess: unknown;
|
|
13
|
+
upgradeUrl: string | null;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/** An open or save dialog, as Gorilla Engine's `openFileChooser` takes it. */
|
|
17
|
+
interface FileDialogOptions {
|
|
18
|
+
allowMultiple?: boolean;
|
|
19
|
+
saveDialog?: boolean;
|
|
20
|
+
warnOnOverwrite?: boolean;
|
|
21
|
+
hint?: string;
|
|
22
|
+
allowedExtensions?: string;
|
|
23
|
+
defaultLocation?: string;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* What the module needs from the plugin's host. Every plugin gets Gorilla
|
|
27
|
+
* Engine's ({@link gorillaEngineHost}); pass parts of your own as `host` for
|
|
28
|
+
* tests, or to route them elsewhere.
|
|
29
|
+
*/
|
|
30
|
+
interface GorillaEngineHost {
|
|
31
|
+
/** The plugin's name, as it was built. Empty when not known. */
|
|
32
|
+
pluginName: () => string;
|
|
33
|
+
/** The plugin's manufacturer, as it was built. Empty when not known. */
|
|
34
|
+
manufacturerName: () => string;
|
|
35
|
+
/** Open a link in the browser. */
|
|
36
|
+
openUrl: (url: string) => void | Promise<void>;
|
|
37
|
+
/** Put text on the clipboard. */
|
|
38
|
+
copyText: (text: string) => Promise<void>;
|
|
39
|
+
/** Show an open or save dialog: the paths chosen, none when cancelled. Absent when there is no dialog. */
|
|
40
|
+
chooseFile?: (options: FileDialogOptions) => Promise<string[]>;
|
|
41
|
+
/** Show a file in the file manager. */
|
|
42
|
+
reveal: (file: string) => Promise<void>;
|
|
43
|
+
/** The folder downloads go to, and the machine file when there is no dialog. */
|
|
44
|
+
downloadsFolder: () => string;
|
|
45
|
+
/** Turn the plugin's MIDI and audio on or off. Absent when the host can't. */
|
|
46
|
+
setAudioAndMidi?: (enabled: boolean) => void;
|
|
47
|
+
/**
|
|
48
|
+
* Calls the listener when the plugin's window gains or loses focus, and
|
|
49
|
+
* returns a function that stops it. Absent when the host doesn't say, as
|
|
50
|
+
* Gorilla Engine doesn't: the overlay then goes by the pointer entering it.
|
|
51
|
+
*/
|
|
52
|
+
onFocusChange?: (listener: (focused: boolean) => void) => () => void;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Gorilla Engine's host: its browser call, file dialogs and MIDI and audio
|
|
56
|
+
* switches, and the system's clipboard and file manager, which Gorilla Engine
|
|
57
|
+
* has no calls for.
|
|
58
|
+
*/
|
|
59
|
+
declare function gorillaEngineHost(): GorillaEngineHost;
|
|
60
|
+
/** The names of the folder a license is kept in, apart from how the plugin is branded. */
|
|
61
|
+
interface LicenseStorage {
|
|
62
|
+
manufacturer: string;
|
|
63
|
+
plugin: string;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* Where a Gorilla Engine plugin keeps the license by default: the manufacturer's
|
|
67
|
+
* folder for user data, as Gorilla Engine's own Product Hub library does.
|
|
68
|
+
* `~/Library/Application Support/<manufacturer>/<plugin>/license.mb` on macOS and
|
|
69
|
+
* `%APPDATA%\<manufacturer>\<plugin>\license.mb` on Windows. The names are
|
|
70
|
+
* `storage`'s, or else the ones the plugin was built with. Throws when there
|
|
71
|
+
* are neither, as in a test without Gorilla Engine, rather than pick a folder
|
|
72
|
+
* another plugin could share.
|
|
73
|
+
*/
|
|
74
|
+
declare function defaultLicenseFile(storage?: LicenseStorage, host?: Pick<GorillaEngineHost, 'pluginName' | 'manufacturerName'>): string;
|
|
75
|
+
/** Something the overlay or the host could not do, as `onError` hears of it. */
|
|
76
|
+
interface GorillaEngineFailure {
|
|
77
|
+
/** What failed: the overlay's action, such as `openLink`, or `audioAndMidi`. */
|
|
78
|
+
action: string;
|
|
79
|
+
/** The SDK's error type, the module's error kind (`notLicensed`, `busy`, ...), or `internal`. */
|
|
80
|
+
kind: string;
|
|
81
|
+
message: string;
|
|
82
|
+
error: unknown;
|
|
83
|
+
}
|
|
84
|
+
/** A report for support, without the license, links, personal details or the device's identity. */
|
|
85
|
+
interface GorillaEngineDiagnostics {
|
|
86
|
+
module: string;
|
|
87
|
+
licensing: string;
|
|
88
|
+
platform: string;
|
|
89
|
+
/** Where the license is kept, with the home folder as `~`. */
|
|
90
|
+
licenseFile: string;
|
|
91
|
+
status: ActivationStatus;
|
|
92
|
+
licensed: boolean;
|
|
93
|
+
/** Which of the host's optional parts are there. */
|
|
94
|
+
host: {
|
|
95
|
+
gorillaEngine: boolean;
|
|
96
|
+
fileDialog: boolean;
|
|
97
|
+
audioAndMidi: boolean;
|
|
98
|
+
focus: boolean;
|
|
99
|
+
};
|
|
100
|
+
/** Whether the module gates MIDI and audio, and whether it last turned them on. Null before it has. */
|
|
101
|
+
audioAndMidi: {
|
|
102
|
+
gated: boolean;
|
|
103
|
+
enabled: boolean | null;
|
|
104
|
+
};
|
|
105
|
+
overlayVisible: boolean;
|
|
106
|
+
}
|
|
107
|
+
/** Branding and behaviour of the built-in activation overlay. */
|
|
108
|
+
interface GorillaEngineUiOptions extends ActivationUiOptions {
|
|
109
|
+
/**
|
|
110
|
+
* The product mark in the header: an image among the plugin's assets, such as
|
|
111
|
+
* `images/logo.png`. Without one, a sun mark is drawn in the accent colour.
|
|
112
|
+
*/
|
|
113
|
+
logo?: string;
|
|
114
|
+
/**
|
|
115
|
+
* The plugin's fonts, as paths among its assets (`fonts/Inter-Regular.otf`).
|
|
116
|
+
* Gorilla Engine draws with the system's font otherwise.
|
|
117
|
+
*/
|
|
118
|
+
fonts?: {
|
|
119
|
+
regular?: string;
|
|
120
|
+
medium?: string;
|
|
121
|
+
semibold?: string;
|
|
122
|
+
mono?: string;
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
/** What {@link MoonbaseGorillaEngine} is built from. */
|
|
126
|
+
interface MoonbaseGorillaEngineOptions extends Omit<ActivationControllerOptions, 'licenseFile' | 'openUrl' | 'productName' | 'accountName'> {
|
|
127
|
+
/** Where the license is kept. Defaults to {@link defaultLicenseFile}. */
|
|
128
|
+
licenseFile?: string;
|
|
129
|
+
/**
|
|
130
|
+
* The names of the folder the license is kept in, instead of the names the
|
|
131
|
+
* plugin was built with. Set them once and keep them, so that renaming the
|
|
132
|
+
* plugin keeps its customers' licenses.
|
|
133
|
+
*/
|
|
134
|
+
storage?: LicenseStorage;
|
|
135
|
+
/**
|
|
136
|
+
* Where earlier versions of the plugin kept the license. When the license
|
|
137
|
+
* file is missing, the first of these that exists is copied to it at startup
|
|
138
|
+
* and checked like any stored license. The old file stays, for versions still
|
|
139
|
+
* installed beside this one.
|
|
140
|
+
*/
|
|
141
|
+
previousLicenseFiles?: string[];
|
|
142
|
+
/** Opens a link in the browser: `host.openUrl`, for short. */
|
|
143
|
+
openUrl?: (url: string) => void | Promise<void>;
|
|
144
|
+
/** The host's browser, clipboard, dialogs and MIDI and audio switches. Defaults to Gorilla Engine's. */
|
|
145
|
+
host?: Partial<GorillaEngineHost>;
|
|
146
|
+
/**
|
|
147
|
+
* Turn the plugin's MIDI and audio on while it is licensed (a license or a
|
|
148
|
+
* trial) and off while it is not, through `GorillaEngine.getPluginMM` and
|
|
149
|
+
* `getPluginAE`: off from `start()`, until the stored license is checked. Pair
|
|
150
|
+
* it with the project's `audioEnabledOnStartup` and `midiEnabledOnStartup`
|
|
151
|
+
* set to false, which cover the moment before the plugin's JavaScript runs.
|
|
152
|
+
* On by default.
|
|
153
|
+
*/
|
|
154
|
+
lockAudioAndMidi?: boolean;
|
|
155
|
+
/**
|
|
156
|
+
* Called with whatever the overlay or the host could not do, such as open the
|
|
157
|
+
* browser. Defaults to a warning in the log.
|
|
158
|
+
*/
|
|
159
|
+
onError?: (failure: GorillaEngineFailure) => void;
|
|
160
|
+
/** The built-in activation overlay's branding and behaviour. */
|
|
161
|
+
ui?: GorillaEngineUiOptions;
|
|
162
|
+
}
|
|
163
|
+
/** What the activation overlay shows, besides the license state. */
|
|
164
|
+
interface ActivationUiState {
|
|
165
|
+
/** Whether the overlay is up. */
|
|
166
|
+
visible: boolean;
|
|
167
|
+
/** The screen it was last asked to open on, and a count that moves with every ask. */
|
|
168
|
+
screen: ActivationScreen | null;
|
|
169
|
+
request: number;
|
|
170
|
+
download: DownloadState;
|
|
171
|
+
}
|
|
172
|
+
/**
|
|
173
|
+
* Moonbase licensing for a Gorilla Engine plugin: the {@link ActivationController},
|
|
174
|
+
* with Gorilla Engine's runtime for the browser, file dialogs and the plugin's
|
|
175
|
+
* MIDI and audio, and the state behind the `MoonbaseActivation` overlay.
|
|
176
|
+
*
|
|
177
|
+
* Create one per plugin instance, at the top level of the plugin's script
|
|
178
|
+
* rather than in a component, and call {@link start}. It lives as long as the
|
|
179
|
+
* plugin does: closing the plugin's window leaves it running, and nothing needs
|
|
180
|
+
* to dispose it. Instances share the license file, so activating in one unlocks
|
|
181
|
+
* the others within a few seconds.
|
|
182
|
+
*/
|
|
183
|
+
declare class MoonbaseGorillaEngine extends ActivationController {
|
|
184
|
+
/** The overlay's branding and behaviour. */
|
|
185
|
+
readonly ui: GorillaEngineUiOptions;
|
|
186
|
+
/** The endpoint, for the overlay's links. */
|
|
187
|
+
readonly endpoint: string;
|
|
188
|
+
private readonly lockAudioAndMidi;
|
|
189
|
+
private readonly host;
|
|
190
|
+
private readonly previousLicenseFiles;
|
|
191
|
+
private readonly onError;
|
|
192
|
+
private readonly uiListeners;
|
|
193
|
+
private uiState;
|
|
194
|
+
private lastLicensed;
|
|
195
|
+
private gated;
|
|
196
|
+
private gateMissingReported;
|
|
197
|
+
private downloaded;
|
|
198
|
+
private name;
|
|
199
|
+
private hasStarted;
|
|
200
|
+
private disposed;
|
|
201
|
+
private stopFocus;
|
|
202
|
+
/** Aborts the update download when the instance is disposed. */
|
|
203
|
+
private readonly aborts;
|
|
204
|
+
constructor(options: MoonbaseGorillaEngineOptions);
|
|
205
|
+
/**
|
|
206
|
+
* Validate the stored license, start watching it, and bring the overlay up
|
|
207
|
+
* when the plugin has no license. Call once per plugin instance; a disposed
|
|
208
|
+
* instance can't start again.
|
|
209
|
+
*/
|
|
210
|
+
start(): void;
|
|
211
|
+
/**
|
|
212
|
+
* Stop watching the license and stop telling the overlay anything. For tests
|
|
213
|
+
* and development reloads: a plugin does not need it. Safe to call twice;
|
|
214
|
+
* afterwards the overlay calls do nothing and {@link start} throws.
|
|
215
|
+
*/
|
|
216
|
+
dispose(): void;
|
|
217
|
+
/** When the license file is missing, take the one an earlier version kept. */
|
|
218
|
+
private importPreviousLicense;
|
|
219
|
+
/**
|
|
220
|
+
* Hand a failure to `onError`: the overlay does with every action that
|
|
221
|
+
* fails, and the module with the host's.
|
|
222
|
+
*/
|
|
223
|
+
reportError(action: string, error: unknown): void;
|
|
224
|
+
/** A report for support: versions, where the license is kept and what the host can do, but nothing personal. */
|
|
225
|
+
diagnostics(): GorillaEngineDiagnostics;
|
|
226
|
+
/** This computer's name, as the activation screen shows it. */
|
|
227
|
+
get deviceName(): string;
|
|
228
|
+
/** What the overlay shows, besides the license state. */
|
|
229
|
+
uiSnapshot(): ActivationUiState;
|
|
230
|
+
/** Called whenever {@link uiSnapshot} changes. Returns a function that stops it. */
|
|
231
|
+
subscribeUi(listener: () => void): () => void;
|
|
232
|
+
private setUi;
|
|
233
|
+
private afterStateChange;
|
|
234
|
+
/** Turn MIDI and audio on or off, saying so when the host can't. */
|
|
235
|
+
private gate;
|
|
236
|
+
/**
|
|
237
|
+
* Show the activation overlay, optionally on a particular screen. Without one
|
|
238
|
+
* it shows whatever the license state calls for.
|
|
239
|
+
*/
|
|
240
|
+
present(screen?: ActivationScreen): void;
|
|
241
|
+
/** Take the overlay down. */
|
|
242
|
+
closeUi(): void;
|
|
243
|
+
/** Copy text to the clipboard, for the activation link and the license id. */
|
|
244
|
+
copyText(text: string): Promise<void>;
|
|
245
|
+
/** Show a file in the file manager. */
|
|
246
|
+
reveal(file: string): Promise<void>;
|
|
247
|
+
private downloadsFolder;
|
|
248
|
+
/**
|
|
249
|
+
* Save the machine file for offline activation: through Gorilla Engine's save
|
|
250
|
+
* dialog, or into Downloads, shown in the file manager. Null when the customer
|
|
251
|
+
* cancels.
|
|
252
|
+
*/
|
|
253
|
+
saveMachineFile(): Promise<string | null>;
|
|
254
|
+
/** Pick the license file the customer got back for offline activation. Null when they cancel. */
|
|
255
|
+
chooseLicenseFile(): Promise<{
|
|
256
|
+
name: string;
|
|
257
|
+
text: string;
|
|
258
|
+
} | null>;
|
|
259
|
+
/** Read a license file the customer dropped or picked. */
|
|
260
|
+
readLicenseFile(file: string): Promise<{
|
|
261
|
+
name: string;
|
|
262
|
+
text: string;
|
|
263
|
+
}>;
|
|
264
|
+
/**
|
|
265
|
+
* Download the latest installer for this platform into Downloads, reporting
|
|
266
|
+
* progress to the overlay, then show it in the file manager.
|
|
267
|
+
*/
|
|
268
|
+
downloadUpdate(): Promise<void>;
|
|
269
|
+
/** Show the downloaded installer in the file manager again. */
|
|
270
|
+
revealUpdate(): Promise<void>;
|
|
271
|
+
/**
|
|
272
|
+
* Open a link from the overlay in the browser: the pending activation, the
|
|
273
|
+
* store, or Moonbase's site from the footer.
|
|
274
|
+
*/
|
|
275
|
+
openLink(url: string): Promise<void>;
|
|
276
|
+
}
|
|
277
|
+
/**
|
|
278
|
+
* Moonbase licensing for a Gorilla Engine plugin:
|
|
279
|
+
*
|
|
280
|
+
* ```ts
|
|
281
|
+
* import { createMoonbase } from '@moonbase.sh/gorilla-engine'
|
|
282
|
+
*
|
|
283
|
+
* const moonbase = createMoonbase({
|
|
284
|
+
* endpoint: 'https://your-store.moonbase.sh',
|
|
285
|
+
* productId: 'your-product',
|
|
286
|
+
* publicKey: MOONBASE_PUBLIC_KEY,
|
|
287
|
+
* appVersion: '1.2.0',
|
|
288
|
+
* ui: { productName: 'Solstice', manufacturerName: 'Helio Audio' },
|
|
289
|
+
* })
|
|
290
|
+
* moonbase.start()
|
|
291
|
+
* ```
|
|
292
|
+
*/
|
|
293
|
+
declare function createMoonbase(options: MoonbaseGorillaEngineOptions): MoonbaseGorillaEngine;
|
|
294
|
+
|
|
295
|
+
/** The license state, kept current: for gating features in the plugin's own UI. */
|
|
296
|
+
declare function useMoonbaseState(moonbase: MoonbaseGorillaEngine): ActivationState;
|
|
297
|
+
/** Props of {@link MoonbaseActivation}. */
|
|
298
|
+
interface MoonbaseActivationProps {
|
|
299
|
+
moonbase: MoonbaseGorillaEngine;
|
|
300
|
+
/** The plugin window's size: the overlay covers it. */
|
|
301
|
+
width: number;
|
|
302
|
+
height: number;
|
|
303
|
+
x?: number;
|
|
304
|
+
y?: number;
|
|
305
|
+
}
|
|
306
|
+
/**
|
|
307
|
+
* The activation overlay: the "Solstice Activation" screens in a panel over the
|
|
308
|
+
* plugin's interface, which it covers and takes every click from while it is up.
|
|
309
|
+
* It comes up by itself while the plugin has no license, and cannot be closed
|
|
310
|
+
* until it has one; `moonbase.present()` brings it up on demand. Render it last,
|
|
311
|
+
* over everything else:
|
|
312
|
+
*
|
|
313
|
+
* ```tsx
|
|
314
|
+
* <geLabel width={920} height={590}>
|
|
315
|
+
* <PluginUI />
|
|
316
|
+
* <MoonbaseActivation moonbase={moonbase} width={920} height={590} />
|
|
317
|
+
* </geLabel>
|
|
318
|
+
* ```
|
|
319
|
+
*/
|
|
320
|
+
declare function MoonbaseActivation(props: MoonbaseActivationProps): ReactElement | null;
|
|
321
|
+
|
|
322
|
+
export { type ActivationUiState, type FileDialogOptions, type GorillaEngineDiagnostics, type GorillaEngineFailure, type GorillaEngineHost, type GorillaEngineUiOptions, type LicenseStorage, MoonbaseActivation, type MoonbaseActivationProps, MoonbaseGorillaEngine, type MoonbaseGorillaEngineOptions, createMoonbase, defaultLicenseFile, gorillaEngineHost, useMoonbaseState };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,322 @@
|
|
|
1
|
+
import { ActivationStatus, ActivationUiOptions, ActivationControllerOptions, ActivationScreen, ActivationController, ActivationState } from '@moonbase.sh/licensing';
|
|
2
|
+
export { ActivationError, ActivationErrorKind, ActivationLogger, ActivationScreen, ActivationState, ActivationStatus, ActivationStrings, ActivationUiOptions, LicenseView, LockReason, MoonbaseError, ReleaseNotCoveredError, TrialFeature } from '@moonbase.sh/licensing';
|
|
3
|
+
import { ReactElement } from 'react';
|
|
4
|
+
|
|
5
|
+
/** How the update download is going, as the update screen shows it. */
|
|
6
|
+
interface DownloadState {
|
|
7
|
+
phase: 'idle' | 'downloading' | 'done' | 'failed' | 'notCovered';
|
|
8
|
+
progress: number | null;
|
|
9
|
+
path: string | null;
|
|
10
|
+
error: string | null;
|
|
11
|
+
/** For `notCovered`: what the customer's licenses cover, and where to upgrade. */
|
|
12
|
+
releaseAccess: unknown;
|
|
13
|
+
upgradeUrl: string | null;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/** An open or save dialog, as Gorilla Engine's `openFileChooser` takes it. */
|
|
17
|
+
interface FileDialogOptions {
|
|
18
|
+
allowMultiple?: boolean;
|
|
19
|
+
saveDialog?: boolean;
|
|
20
|
+
warnOnOverwrite?: boolean;
|
|
21
|
+
hint?: string;
|
|
22
|
+
allowedExtensions?: string;
|
|
23
|
+
defaultLocation?: string;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* What the module needs from the plugin's host. Every plugin gets Gorilla
|
|
27
|
+
* Engine's ({@link gorillaEngineHost}); pass parts of your own as `host` for
|
|
28
|
+
* tests, or to route them elsewhere.
|
|
29
|
+
*/
|
|
30
|
+
interface GorillaEngineHost {
|
|
31
|
+
/** The plugin's name, as it was built. Empty when not known. */
|
|
32
|
+
pluginName: () => string;
|
|
33
|
+
/** The plugin's manufacturer, as it was built. Empty when not known. */
|
|
34
|
+
manufacturerName: () => string;
|
|
35
|
+
/** Open a link in the browser. */
|
|
36
|
+
openUrl: (url: string) => void | Promise<void>;
|
|
37
|
+
/** Put text on the clipboard. */
|
|
38
|
+
copyText: (text: string) => Promise<void>;
|
|
39
|
+
/** Show an open or save dialog: the paths chosen, none when cancelled. Absent when there is no dialog. */
|
|
40
|
+
chooseFile?: (options: FileDialogOptions) => Promise<string[]>;
|
|
41
|
+
/** Show a file in the file manager. */
|
|
42
|
+
reveal: (file: string) => Promise<void>;
|
|
43
|
+
/** The folder downloads go to, and the machine file when there is no dialog. */
|
|
44
|
+
downloadsFolder: () => string;
|
|
45
|
+
/** Turn the plugin's MIDI and audio on or off. Absent when the host can't. */
|
|
46
|
+
setAudioAndMidi?: (enabled: boolean) => void;
|
|
47
|
+
/**
|
|
48
|
+
* Calls the listener when the plugin's window gains or loses focus, and
|
|
49
|
+
* returns a function that stops it. Absent when the host doesn't say, as
|
|
50
|
+
* Gorilla Engine doesn't: the overlay then goes by the pointer entering it.
|
|
51
|
+
*/
|
|
52
|
+
onFocusChange?: (listener: (focused: boolean) => void) => () => void;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Gorilla Engine's host: its browser call, file dialogs and MIDI and audio
|
|
56
|
+
* switches, and the system's clipboard and file manager, which Gorilla Engine
|
|
57
|
+
* has no calls for.
|
|
58
|
+
*/
|
|
59
|
+
declare function gorillaEngineHost(): GorillaEngineHost;
|
|
60
|
+
/** The names of the folder a license is kept in, apart from how the plugin is branded. */
|
|
61
|
+
interface LicenseStorage {
|
|
62
|
+
manufacturer: string;
|
|
63
|
+
plugin: string;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* Where a Gorilla Engine plugin keeps the license by default: the manufacturer's
|
|
67
|
+
* folder for user data, as Gorilla Engine's own Product Hub library does.
|
|
68
|
+
* `~/Library/Application Support/<manufacturer>/<plugin>/license.mb` on macOS and
|
|
69
|
+
* `%APPDATA%\<manufacturer>\<plugin>\license.mb` on Windows. The names are
|
|
70
|
+
* `storage`'s, or else the ones the plugin was built with. Throws when there
|
|
71
|
+
* are neither, as in a test without Gorilla Engine, rather than pick a folder
|
|
72
|
+
* another plugin could share.
|
|
73
|
+
*/
|
|
74
|
+
declare function defaultLicenseFile(storage?: LicenseStorage, host?: Pick<GorillaEngineHost, 'pluginName' | 'manufacturerName'>): string;
|
|
75
|
+
/** Something the overlay or the host could not do, as `onError` hears of it. */
|
|
76
|
+
interface GorillaEngineFailure {
|
|
77
|
+
/** What failed: the overlay's action, such as `openLink`, or `audioAndMidi`. */
|
|
78
|
+
action: string;
|
|
79
|
+
/** The SDK's error type, the module's error kind (`notLicensed`, `busy`, ...), or `internal`. */
|
|
80
|
+
kind: string;
|
|
81
|
+
message: string;
|
|
82
|
+
error: unknown;
|
|
83
|
+
}
|
|
84
|
+
/** A report for support, without the license, links, personal details or the device's identity. */
|
|
85
|
+
interface GorillaEngineDiagnostics {
|
|
86
|
+
module: string;
|
|
87
|
+
licensing: string;
|
|
88
|
+
platform: string;
|
|
89
|
+
/** Where the license is kept, with the home folder as `~`. */
|
|
90
|
+
licenseFile: string;
|
|
91
|
+
status: ActivationStatus;
|
|
92
|
+
licensed: boolean;
|
|
93
|
+
/** Which of the host's optional parts are there. */
|
|
94
|
+
host: {
|
|
95
|
+
gorillaEngine: boolean;
|
|
96
|
+
fileDialog: boolean;
|
|
97
|
+
audioAndMidi: boolean;
|
|
98
|
+
focus: boolean;
|
|
99
|
+
};
|
|
100
|
+
/** Whether the module gates MIDI and audio, and whether it last turned them on. Null before it has. */
|
|
101
|
+
audioAndMidi: {
|
|
102
|
+
gated: boolean;
|
|
103
|
+
enabled: boolean | null;
|
|
104
|
+
};
|
|
105
|
+
overlayVisible: boolean;
|
|
106
|
+
}
|
|
107
|
+
/** Branding and behaviour of the built-in activation overlay. */
|
|
108
|
+
interface GorillaEngineUiOptions extends ActivationUiOptions {
|
|
109
|
+
/**
|
|
110
|
+
* The product mark in the header: an image among the plugin's assets, such as
|
|
111
|
+
* `images/logo.png`. Without one, a sun mark is drawn in the accent colour.
|
|
112
|
+
*/
|
|
113
|
+
logo?: string;
|
|
114
|
+
/**
|
|
115
|
+
* The plugin's fonts, as paths among its assets (`fonts/Inter-Regular.otf`).
|
|
116
|
+
* Gorilla Engine draws with the system's font otherwise.
|
|
117
|
+
*/
|
|
118
|
+
fonts?: {
|
|
119
|
+
regular?: string;
|
|
120
|
+
medium?: string;
|
|
121
|
+
semibold?: string;
|
|
122
|
+
mono?: string;
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
/** What {@link MoonbaseGorillaEngine} is built from. */
|
|
126
|
+
interface MoonbaseGorillaEngineOptions extends Omit<ActivationControllerOptions, 'licenseFile' | 'openUrl' | 'productName' | 'accountName'> {
|
|
127
|
+
/** Where the license is kept. Defaults to {@link defaultLicenseFile}. */
|
|
128
|
+
licenseFile?: string;
|
|
129
|
+
/**
|
|
130
|
+
* The names of the folder the license is kept in, instead of the names the
|
|
131
|
+
* plugin was built with. Set them once and keep them, so that renaming the
|
|
132
|
+
* plugin keeps its customers' licenses.
|
|
133
|
+
*/
|
|
134
|
+
storage?: LicenseStorage;
|
|
135
|
+
/**
|
|
136
|
+
* Where earlier versions of the plugin kept the license. When the license
|
|
137
|
+
* file is missing, the first of these that exists is copied to it at startup
|
|
138
|
+
* and checked like any stored license. The old file stays, for versions still
|
|
139
|
+
* installed beside this one.
|
|
140
|
+
*/
|
|
141
|
+
previousLicenseFiles?: string[];
|
|
142
|
+
/** Opens a link in the browser: `host.openUrl`, for short. */
|
|
143
|
+
openUrl?: (url: string) => void | Promise<void>;
|
|
144
|
+
/** The host's browser, clipboard, dialogs and MIDI and audio switches. Defaults to Gorilla Engine's. */
|
|
145
|
+
host?: Partial<GorillaEngineHost>;
|
|
146
|
+
/**
|
|
147
|
+
* Turn the plugin's MIDI and audio on while it is licensed (a license or a
|
|
148
|
+
* trial) and off while it is not, through `GorillaEngine.getPluginMM` and
|
|
149
|
+
* `getPluginAE`: off from `start()`, until the stored license is checked. Pair
|
|
150
|
+
* it with the project's `audioEnabledOnStartup` and `midiEnabledOnStartup`
|
|
151
|
+
* set to false, which cover the moment before the plugin's JavaScript runs.
|
|
152
|
+
* On by default.
|
|
153
|
+
*/
|
|
154
|
+
lockAudioAndMidi?: boolean;
|
|
155
|
+
/**
|
|
156
|
+
* Called with whatever the overlay or the host could not do, such as open the
|
|
157
|
+
* browser. Defaults to a warning in the log.
|
|
158
|
+
*/
|
|
159
|
+
onError?: (failure: GorillaEngineFailure) => void;
|
|
160
|
+
/** The built-in activation overlay's branding and behaviour. */
|
|
161
|
+
ui?: GorillaEngineUiOptions;
|
|
162
|
+
}
|
|
163
|
+
/** What the activation overlay shows, besides the license state. */
|
|
164
|
+
interface ActivationUiState {
|
|
165
|
+
/** Whether the overlay is up. */
|
|
166
|
+
visible: boolean;
|
|
167
|
+
/** The screen it was last asked to open on, and a count that moves with every ask. */
|
|
168
|
+
screen: ActivationScreen | null;
|
|
169
|
+
request: number;
|
|
170
|
+
download: DownloadState;
|
|
171
|
+
}
|
|
172
|
+
/**
|
|
173
|
+
* Moonbase licensing for a Gorilla Engine plugin: the {@link ActivationController},
|
|
174
|
+
* with Gorilla Engine's runtime for the browser, file dialogs and the plugin's
|
|
175
|
+
* MIDI and audio, and the state behind the `MoonbaseActivation` overlay.
|
|
176
|
+
*
|
|
177
|
+
* Create one per plugin instance, at the top level of the plugin's script
|
|
178
|
+
* rather than in a component, and call {@link start}. It lives as long as the
|
|
179
|
+
* plugin does: closing the plugin's window leaves it running, and nothing needs
|
|
180
|
+
* to dispose it. Instances share the license file, so activating in one unlocks
|
|
181
|
+
* the others within a few seconds.
|
|
182
|
+
*/
|
|
183
|
+
declare class MoonbaseGorillaEngine extends ActivationController {
|
|
184
|
+
/** The overlay's branding and behaviour. */
|
|
185
|
+
readonly ui: GorillaEngineUiOptions;
|
|
186
|
+
/** The endpoint, for the overlay's links. */
|
|
187
|
+
readonly endpoint: string;
|
|
188
|
+
private readonly lockAudioAndMidi;
|
|
189
|
+
private readonly host;
|
|
190
|
+
private readonly previousLicenseFiles;
|
|
191
|
+
private readonly onError;
|
|
192
|
+
private readonly uiListeners;
|
|
193
|
+
private uiState;
|
|
194
|
+
private lastLicensed;
|
|
195
|
+
private gated;
|
|
196
|
+
private gateMissingReported;
|
|
197
|
+
private downloaded;
|
|
198
|
+
private name;
|
|
199
|
+
private hasStarted;
|
|
200
|
+
private disposed;
|
|
201
|
+
private stopFocus;
|
|
202
|
+
/** Aborts the update download when the instance is disposed. */
|
|
203
|
+
private readonly aborts;
|
|
204
|
+
constructor(options: MoonbaseGorillaEngineOptions);
|
|
205
|
+
/**
|
|
206
|
+
* Validate the stored license, start watching it, and bring the overlay up
|
|
207
|
+
* when the plugin has no license. Call once per plugin instance; a disposed
|
|
208
|
+
* instance can't start again.
|
|
209
|
+
*/
|
|
210
|
+
start(): void;
|
|
211
|
+
/**
|
|
212
|
+
* Stop watching the license and stop telling the overlay anything. For tests
|
|
213
|
+
* and development reloads: a plugin does not need it. Safe to call twice;
|
|
214
|
+
* afterwards the overlay calls do nothing and {@link start} throws.
|
|
215
|
+
*/
|
|
216
|
+
dispose(): void;
|
|
217
|
+
/** When the license file is missing, take the one an earlier version kept. */
|
|
218
|
+
private importPreviousLicense;
|
|
219
|
+
/**
|
|
220
|
+
* Hand a failure to `onError`: the overlay does with every action that
|
|
221
|
+
* fails, and the module with the host's.
|
|
222
|
+
*/
|
|
223
|
+
reportError(action: string, error: unknown): void;
|
|
224
|
+
/** A report for support: versions, where the license is kept and what the host can do, but nothing personal. */
|
|
225
|
+
diagnostics(): GorillaEngineDiagnostics;
|
|
226
|
+
/** This computer's name, as the activation screen shows it. */
|
|
227
|
+
get deviceName(): string;
|
|
228
|
+
/** What the overlay shows, besides the license state. */
|
|
229
|
+
uiSnapshot(): ActivationUiState;
|
|
230
|
+
/** Called whenever {@link uiSnapshot} changes. Returns a function that stops it. */
|
|
231
|
+
subscribeUi(listener: () => void): () => void;
|
|
232
|
+
private setUi;
|
|
233
|
+
private afterStateChange;
|
|
234
|
+
/** Turn MIDI and audio on or off, saying so when the host can't. */
|
|
235
|
+
private gate;
|
|
236
|
+
/**
|
|
237
|
+
* Show the activation overlay, optionally on a particular screen. Without one
|
|
238
|
+
* it shows whatever the license state calls for.
|
|
239
|
+
*/
|
|
240
|
+
present(screen?: ActivationScreen): void;
|
|
241
|
+
/** Take the overlay down. */
|
|
242
|
+
closeUi(): void;
|
|
243
|
+
/** Copy text to the clipboard, for the activation link and the license id. */
|
|
244
|
+
copyText(text: string): Promise<void>;
|
|
245
|
+
/** Show a file in the file manager. */
|
|
246
|
+
reveal(file: string): Promise<void>;
|
|
247
|
+
private downloadsFolder;
|
|
248
|
+
/**
|
|
249
|
+
* Save the machine file for offline activation: through Gorilla Engine's save
|
|
250
|
+
* dialog, or into Downloads, shown in the file manager. Null when the customer
|
|
251
|
+
* cancels.
|
|
252
|
+
*/
|
|
253
|
+
saveMachineFile(): Promise<string | null>;
|
|
254
|
+
/** Pick the license file the customer got back for offline activation. Null when they cancel. */
|
|
255
|
+
chooseLicenseFile(): Promise<{
|
|
256
|
+
name: string;
|
|
257
|
+
text: string;
|
|
258
|
+
} | null>;
|
|
259
|
+
/** Read a license file the customer dropped or picked. */
|
|
260
|
+
readLicenseFile(file: string): Promise<{
|
|
261
|
+
name: string;
|
|
262
|
+
text: string;
|
|
263
|
+
}>;
|
|
264
|
+
/**
|
|
265
|
+
* Download the latest installer for this platform into Downloads, reporting
|
|
266
|
+
* progress to the overlay, then show it in the file manager.
|
|
267
|
+
*/
|
|
268
|
+
downloadUpdate(): Promise<void>;
|
|
269
|
+
/** Show the downloaded installer in the file manager again. */
|
|
270
|
+
revealUpdate(): Promise<void>;
|
|
271
|
+
/**
|
|
272
|
+
* Open a link from the overlay in the browser: the pending activation, the
|
|
273
|
+
* store, or Moonbase's site from the footer.
|
|
274
|
+
*/
|
|
275
|
+
openLink(url: string): Promise<void>;
|
|
276
|
+
}
|
|
277
|
+
/**
|
|
278
|
+
* Moonbase licensing for a Gorilla Engine plugin:
|
|
279
|
+
*
|
|
280
|
+
* ```ts
|
|
281
|
+
* import { createMoonbase } from '@moonbase.sh/gorilla-engine'
|
|
282
|
+
*
|
|
283
|
+
* const moonbase = createMoonbase({
|
|
284
|
+
* endpoint: 'https://your-store.moonbase.sh',
|
|
285
|
+
* productId: 'your-product',
|
|
286
|
+
* publicKey: MOONBASE_PUBLIC_KEY,
|
|
287
|
+
* appVersion: '1.2.0',
|
|
288
|
+
* ui: { productName: 'Solstice', manufacturerName: 'Helio Audio' },
|
|
289
|
+
* })
|
|
290
|
+
* moonbase.start()
|
|
291
|
+
* ```
|
|
292
|
+
*/
|
|
293
|
+
declare function createMoonbase(options: MoonbaseGorillaEngineOptions): MoonbaseGorillaEngine;
|
|
294
|
+
|
|
295
|
+
/** The license state, kept current: for gating features in the plugin's own UI. */
|
|
296
|
+
declare function useMoonbaseState(moonbase: MoonbaseGorillaEngine): ActivationState;
|
|
297
|
+
/** Props of {@link MoonbaseActivation}. */
|
|
298
|
+
interface MoonbaseActivationProps {
|
|
299
|
+
moonbase: MoonbaseGorillaEngine;
|
|
300
|
+
/** The plugin window's size: the overlay covers it. */
|
|
301
|
+
width: number;
|
|
302
|
+
height: number;
|
|
303
|
+
x?: number;
|
|
304
|
+
y?: number;
|
|
305
|
+
}
|
|
306
|
+
/**
|
|
307
|
+
* The activation overlay: the "Solstice Activation" screens in a panel over the
|
|
308
|
+
* plugin's interface, which it covers and takes every click from while it is up.
|
|
309
|
+
* It comes up by itself while the plugin has no license, and cannot be closed
|
|
310
|
+
* until it has one; `moonbase.present()` brings it up on demand. Render it last,
|
|
311
|
+
* over everything else:
|
|
312
|
+
*
|
|
313
|
+
* ```tsx
|
|
314
|
+
* <geLabel width={920} height={590}>
|
|
315
|
+
* <PluginUI />
|
|
316
|
+
* <MoonbaseActivation moonbase={moonbase} width={920} height={590} />
|
|
317
|
+
* </geLabel>
|
|
318
|
+
* ```
|
|
319
|
+
*/
|
|
320
|
+
declare function MoonbaseActivation(props: MoonbaseActivationProps): ReactElement | null;
|
|
321
|
+
|
|
322
|
+
export { type ActivationUiState, type FileDialogOptions, type GorillaEngineDiagnostics, type GorillaEngineFailure, type GorillaEngineHost, type GorillaEngineUiOptions, type LicenseStorage, MoonbaseActivation, type MoonbaseActivationProps, MoonbaseGorillaEngine, type MoonbaseGorillaEngineOptions, createMoonbase, defaultLicenseFile, gorillaEngineHost, useMoonbaseState };
|