@moonbase.sh/licensing 3.2.3 → 3.4.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 +225 -4
- package/dist/index.cjs +2397 -64
- package/dist/index.d.cts +1908 -44
- package/dist/index.d.ts +1908 -44
- package/dist/index.js +2387 -66
- package/package.json +17 -2
- package/release-access-vectors.json +150 -0
package/README.md
CHANGED
|
@@ -4,6 +4,14 @@ Node.js licensing SDK for Moonbase products.
|
|
|
4
4
|
|
|
5
5
|
Use it to request activation, validate licenses locally and online, persist licenses, and revoke activations.
|
|
6
6
|
|
|
7
|
+
For an Electron app or a Gorilla Engine plugin, use
|
|
8
|
+
[`@moonbase.sh/electron`](https://www.npmjs.com/package/@moonbase.sh/electron) or
|
|
9
|
+
[`@moonbase.sh/gorilla-engine`](https://www.npmjs.com/package/@moonbase.sh/gorilla-engine)
|
|
10
|
+
on top of this package: a finished activation flow, the same one moonbase-cpp's JUCE module and
|
|
11
|
+
tauri-plugin-moonbase have, that validates the stored license at startup, runs browser and offline activation,
|
|
12
|
+
trials, deactivation, add-ons and update downloads, and presents a themeable activation UI whenever the app is
|
|
13
|
+
locked. The state machine underneath both is here, for a UI of your own: see [A UI of your own](#a-ui-of-your-own).
|
|
14
|
+
|
|
7
15
|
Learn more in our official documentation here: https://moonbase.sh/docs/licensing/sdks/node/
|
|
8
16
|
|
|
9
17
|
## Install
|
|
@@ -65,12 +73,14 @@ such as opening the app offline.
|
|
|
65
73
|
|
|
66
74
|
```ts
|
|
67
75
|
import type { License } from '@moonbase.sh/licensing'
|
|
68
|
-
import { ActivationMethod, ErrorType, MoonbaseError } from '@moonbase.sh/licensing'
|
|
76
|
+
import { ActivationMethod, ErrorType, MoonbaseError, ReleaseNotCoveredError } from '@moonbase.sh/licensing'
|
|
69
77
|
|
|
70
78
|
// Moonbase says the license can no longer be used on this device. Anything
|
|
71
79
|
// else, an ErrorType.ApiError or a network failure (which is not a
|
|
72
|
-
// MoonbaseError), only means Moonbase could not be reached right now,
|
|
73
|
-
// ErrorType.StoreClosed that it never will be again (see below)
|
|
80
|
+
// MoonbaseError), only means Moonbase could not be reached right now,
|
|
81
|
+
// ErrorType.StoreClosed that it never will be again (see below), and
|
|
82
|
+
// ErrorType.ReleaseNotCovered that the license is good, just not for this
|
|
83
|
+
// version of the app (see "Licenses that cover some versions").
|
|
74
84
|
const licenseGone = new Set<ErrorType | undefined>([
|
|
75
85
|
ErrorType.LicenseRevoked,
|
|
76
86
|
ErrorType.LicenseActivationRevoked,
|
|
@@ -93,6 +103,14 @@ async function licenseOnStartup(): Promise<License | null> {
|
|
|
93
103
|
return refreshed
|
|
94
104
|
}
|
|
95
105
|
catch (err) {
|
|
106
|
+
if (err instanceof ReleaseNotCoveredError) {
|
|
107
|
+
// Still the customer's license, for the versions it covers: keep the
|
|
108
|
+
// fresh copy Moonbase sent along
|
|
109
|
+
if (err.license)
|
|
110
|
+
await licensing.store.storeLocalLicense(err.license)
|
|
111
|
+
offerUpgrade(err)
|
|
112
|
+
return null
|
|
113
|
+
}
|
|
96
114
|
if (err instanceof MoonbaseError && licenseGone.has(err.type)) {
|
|
97
115
|
await licensing.store.deleteLocalLicense()
|
|
98
116
|
return null // show your activation flow
|
|
@@ -103,12 +121,16 @@ async function licenseOnStartup(): Promise<License | null> {
|
|
|
103
121
|
}
|
|
104
122
|
|
|
105
123
|
try {
|
|
106
|
-
// Signature, device binding and
|
|
124
|
+
// Signature, device binding, expiry and the app version, which needs no network
|
|
107
125
|
return await licensing.validator.validateLicense(localLicense.token)
|
|
108
126
|
}
|
|
109
127
|
catch (err) {
|
|
110
128
|
// Keep the stored token: only Moonbase can say the license is gone, and the
|
|
111
129
|
// next launch that reaches it can still refresh a token that has expired
|
|
130
|
+
if (err instanceof ReleaseNotCoveredError) {
|
|
131
|
+
offerUpgrade(err)
|
|
132
|
+
return null
|
|
133
|
+
}
|
|
112
134
|
if (err instanceof MoonbaseError)
|
|
113
135
|
return null // show your activation flow
|
|
114
136
|
throw err
|
|
@@ -145,6 +167,7 @@ license makes a device independent of Moonbase.
|
|
|
145
167
|
The SDK can report analytics with every activation, trial request, and validation. These are configured once on the `MoonbaseLicensing` config and sent automatically; there's no per-call parameter.
|
|
146
168
|
|
|
147
169
|
- `appVersion` and `platform` are first-class fields and sent as plain query params. `metadata` is for arbitrary customer-defined keys, sent as `meta[key]=value`.
|
|
170
|
+
- `appVersion` is also the version a license has to cover, for a license that covers only some versions (see below).
|
|
148
171
|
- `platform` auto-detects from `process.platform` (`darwin` → `Mac`, `win32` → `Windows`, `linux` → `Linux`). Set it explicitly to override, or pass `null` to suppress.
|
|
149
172
|
- All three are sent on `requestActivation`, `requestTrial`, and `validateLicense`, never on `revokeLicense`.
|
|
150
173
|
- `metadata` accepts string keys and string values only; empty values are dropped client-side.
|
|
@@ -152,6 +175,139 @@ The SDK can report analytics with every activation, trial request, and validatio
|
|
|
152
175
|
- The config object is re-read on every call, so mutating `metadata` between calls (e.g. to rotate a session id) means the next request picks it up.
|
|
153
176
|
- Keep payloads small; query-string length limits apply.
|
|
154
177
|
|
|
178
|
+
## Licenses that cover some versions
|
|
179
|
+
|
|
180
|
+
A license bought outright can cover only some versions of the app: those released during its updates ("12 months
|
|
181
|
+
of updates"), or every version up to a major ("versions up to 2.x"). The license itself never expires; it just
|
|
182
|
+
doesn't cover the versions after that. It says what it covers in `releaseAccess`, which is absent when it covers
|
|
183
|
+
every version:
|
|
184
|
+
|
|
185
|
+
- `updatesUntil`: releases published until then are covered, and every version while it has not passed.
|
|
186
|
+
- `upToMajor`: every version whose major is at most this is covered.
|
|
187
|
+
- `upToVersion`: once updates have ended, the last version published before they did, covered along with every
|
|
188
|
+
older one. Absent while updates last, and when nothing was published before they ended (then every version is
|
|
189
|
+
covered).
|
|
190
|
+
|
|
191
|
+
The limits add up: a license with both covers a version that either covers.
|
|
192
|
+
|
|
193
|
+
Set `appVersion` for the version to be checked. Activating or validating a license that doesn't cover it throws a
|
|
194
|
+
`ReleaseNotCoveredError` (`ErrorType.ReleaseNotCovered`), and so does `validator.validateLicense` on the device,
|
|
195
|
+
judged by the device clock. Set `enforceReleaseAccess: false` to turn the check on the device off; Moonbase checks
|
|
196
|
+
online activation and validation either way. A license activated offline, from a device token the customer brings to
|
|
197
|
+
the customer portal, is checked only on the device. An `appVersion` that can't be read as a version is not checked. One is read as an optional leading `v`,
|
|
198
|
+
then two to four numbers (a fourth is ignored), with any `-beta` or `+build` suffix dropped, so `3.0.0-beta.2` is
|
|
199
|
+
judged as 3.0.0.
|
|
200
|
+
|
|
201
|
+
Do not delete the stored license on `ReleaseNotCoveredError`, and do not treat it like a revoked one: it still covers
|
|
202
|
+
the versions it did, so the customer can go back to one of them, or upgrade and keep going. Validating online sends
|
|
203
|
+
the license along, freshly issued, in `err.license`, to store in place of the old one. Say what the license covers
|
|
204
|
+
and offer the upgrade:
|
|
205
|
+
|
|
206
|
+
```ts
|
|
207
|
+
function offerUpgrade(err: ReleaseNotCoveredError) {
|
|
208
|
+
const access = err.releaseAccess
|
|
209
|
+
const coversUpTo = access?.upToVersion
|
|
210
|
+
?? (access?.upToMajor !== undefined ? `${access.upToMajor}.x` : undefined)
|
|
211
|
+
|
|
212
|
+
showUpgradeDialog({
|
|
213
|
+
message: coversUpTo
|
|
214
|
+
? `Your license covers versions up to ${coversUpTo}, not ${err.appVersion}.`
|
|
215
|
+
: `Your license doesn't cover version ${err.appVersion}.`,
|
|
216
|
+
// Where the customer buys the upgrade. Only Moonbase knows it, so it is
|
|
217
|
+
// absent when the check on the device refused.
|
|
218
|
+
upgradeUrl: err.upgradeUrl,
|
|
219
|
+
})
|
|
220
|
+
}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
To check another version, such as an update before offering to download it, use `coversVersion`:
|
|
224
|
+
|
|
225
|
+
```ts
|
|
226
|
+
import { coversVersion } from '@moonbase.sh/licensing'
|
|
227
|
+
|
|
228
|
+
if (!coversVersion(license, latestRelease.version)) {
|
|
229
|
+
// offer the upgrade along with the update
|
|
230
|
+
}
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
`coversVersion(license, version, now = new Date())` applies the same rule as Moonbase and every other Moonbase
|
|
234
|
+
SDK. The shipped [`release-access-vectors.json`](./release-access-vectors.json) pins it down case by case, and
|
|
235
|
+
`parseAppVersion` reads a version the way it does.
|
|
236
|
+
|
|
237
|
+
## Add-ons
|
|
238
|
+
|
|
239
|
+
An add-on (a sub-product, with a product ID like `my-app.strings`) that the merchant includes in its main
|
|
240
|
+
product's license travels in the main license, so one validation answers for both. When a device activates or
|
|
241
|
+
validates the main product, it takes a seat of each such add-on the customer owns, and the license lists them in
|
|
242
|
+
`subProducts`:
|
|
243
|
+
|
|
244
|
+
```ts
|
|
245
|
+
import { hasSubProduct } from '@moonbase.sh/licensing'
|
|
246
|
+
|
|
247
|
+
if (hasSubProduct(license, 'strings')) {
|
|
248
|
+
// unlock the strings add-on
|
|
249
|
+
}
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
`hasSubProduct` takes the add-on's own part of its ID or the whole ID. It is true while the license lists the
|
|
253
|
+
add-on as active and it has not expired, which matters for an offline license. An add-on the customer owns, but
|
|
254
|
+
with every seat taken on other devices, is listed with `active: false`. An add-on bought after the device activated
|
|
255
|
+
shows up at the next `validateLicense`.
|
|
256
|
+
|
|
257
|
+
If the customer revokes an add-on's seat on this device (from their account, or the merchant does it for them),
|
|
258
|
+
validating does not take it back: the license lists it with `revoked: true` until the app activates it again. To
|
|
259
|
+
activate add-ons yourself instead of on every activation and validation, set `autoActivateSubProducts: false`.
|
|
260
|
+
Either way, take a seat with:
|
|
261
|
+
|
|
262
|
+
```ts
|
|
263
|
+
const license = await licensing.client.activateSubProduct(localLicense, 'strings')
|
|
264
|
+
await licensing.store.storeLocalLicense(license)
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
It throws `ErrorType.NoEligibleLicense` when the customer doesn't own the add-on or has no free seat of it.
|
|
268
|
+
|
|
269
|
+
To let a customer try an add-on that offers trials, start its trial from the main license and store what comes
|
|
270
|
+
back in its place:
|
|
271
|
+
|
|
272
|
+
```ts
|
|
273
|
+
const license = await licensing.client.requestSubProductTrial(localLicense, 'strings')
|
|
274
|
+
await licensing.store.storeLocalLicense(license)
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
The license must be an online license, not a trial. A customer who owns the add-on gets a seat of it instead, as
|
|
278
|
+
`activateSubProduct` does, and a device gets one trial of each add-on: asking again returns the license with the
|
|
279
|
+
trial it had, expired or not.
|
|
280
|
+
Revoking the main license's activation frees the device's add-on seats too.
|
|
281
|
+
|
|
282
|
+
`ownedSubProductIds` still lists every add-on the customer owns, included in the license or not, without saying
|
|
283
|
+
whether it may be used on this device.
|
|
284
|
+
|
|
285
|
+
To show the customer what else there is, for example on an upgrade screen, list the product's add-ons from the
|
|
286
|
+
license (or a trial) the device holds. Each comes with its prices when it is for sale, whether the customer owns it,
|
|
287
|
+
whether to unlock it here, and its trial:
|
|
288
|
+
|
|
289
|
+
```ts
|
|
290
|
+
const { currency, subProducts } = await licensing.client.listSubProducts(localLicense)
|
|
291
|
+
|
|
292
|
+
for (const addOn of subProducts) {
|
|
293
|
+
const price = addOn.product.defaultVariation?.price[currency]
|
|
294
|
+
if (addOn.active) {
|
|
295
|
+
// owned, or trialing, on this device
|
|
296
|
+
}
|
|
297
|
+
else if (addOn.trial?.status === 'Available') {
|
|
298
|
+
// offer "Try it", which calls requestSubProductTrial
|
|
299
|
+
}
|
|
300
|
+
else if (addOn.buyUrl) {
|
|
301
|
+
// offer "Buy" for `price`, opening addOn.buyUrl in the browser
|
|
302
|
+
}
|
|
303
|
+
}
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
It lists only the add-ons the customer can do something with: ones they own or subscribe to, ones on sale, and ones
|
|
307
|
+
whose trial can be started or is running on this device. `trial.status` is `Available` when
|
|
308
|
+
`requestSubProductTrial` can start one now, `Active` or `Expired` for the trial the device had, and `Unavailable`
|
|
309
|
+
otherwise. Listing changes nothing.
|
|
310
|
+
|
|
155
311
|
## Revoke a license activation
|
|
156
312
|
|
|
157
313
|
```ts
|
|
@@ -319,3 +475,68 @@ invalidates its license) and get no cross-SDK compatibility. Use this only as a
|
|
|
319
475
|
You can inject your own `ILicenseStore` and `IDeviceIdResolver` implementations via the
|
|
320
476
|
`licenseStore` and `deviceIdResolver` configuration options. A custom resolver's id is compared
|
|
321
477
|
literally, so it does not need to follow the `mbd2_` stamp format.
|
|
478
|
+
|
|
479
|
+
## A UI of your own
|
|
480
|
+
|
|
481
|
+
Under `@moonbase.sh/electron` and `@moonbase.sh/gorilla-engine` is `ActivationController`,
|
|
482
|
+
the activation state machine, which you can drive yourself from any Node.js app:
|
|
483
|
+
|
|
484
|
+
```ts
|
|
485
|
+
import { ActivationController } from '@moonbase.sh/licensing'
|
|
486
|
+
|
|
487
|
+
const controller = new ActivationController({
|
|
488
|
+
endpoint: 'https://your-store.moonbase.sh',
|
|
489
|
+
productId: 'your-product',
|
|
490
|
+
publicKey: MOONBASE_PUBLIC_KEY,
|
|
491
|
+
appVersion: '1.2.0',
|
|
492
|
+
licenseFile: '/path/to/license.mb',
|
|
493
|
+
openUrl: url => open(url),
|
|
494
|
+
})
|
|
495
|
+
controller.subscribe(render)
|
|
496
|
+
controller.start()
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
Render whatever `state.status` says:
|
|
500
|
+
|
|
501
|
+
| `status` | Meaning | A typical screen |
|
|
502
|
+
| --- | --- | --- |
|
|
503
|
+
| `loading` | Validating the stored license at startup | A spinner |
|
|
504
|
+
| `unlicensed` | No license; `lockReason` says why, when there was one | Welcome: activate online or offline |
|
|
505
|
+
| `activating` | A browser activation is in progress; `activation.browserUrl` is the link | "Finish in your browser", copy link, cancel |
|
|
506
|
+
| `licensed` | A full license | License details, deactivate |
|
|
507
|
+
| `trial` | A trial; `license.daysRemaining` counts down | Days left, unlock full version |
|
|
508
|
+
| `trialExpired` | The trial ended; `expiredTrial` has it | Buy or activate |
|
|
509
|
+
| `notCovered` | The license doesn't cover this version of the app; `notCovered` has it, what it covers and where to upgrade | Upgrade, or check again |
|
|
510
|
+
|
|
511
|
+
`licensed` says whether there is a valid license right now: a trial being unlocked keeps its license while
|
|
512
|
+
`activating`, so check it rather than the status. `lockReason` is `deactivated`, `expired`, `invalid`, `unverified`
|
|
513
|
+
or `notCovered`. `error` is the last failed operation, with `message` worded for the customer and `detail`, the
|
|
514
|
+
SDK's message, for logs. `update` is a newer release than the app, from the license alone, and `addOns` the add-on
|
|
515
|
+
list once `loadAddOns()` has run. The license in the state carries no token.
|
|
516
|
+
|
|
517
|
+
What runs in the background:
|
|
518
|
+
|
|
519
|
+
- **At startup** the stored license is validated, online when it is due. An expired offline license is removed; an
|
|
520
|
+
ended trial shows as `trialExpired`; a license that doesn't cover this version shows as `notCovered`; a license
|
|
521
|
+
bound to another device locks as `invalid`; one that cannot be checked past the grace period (`gracePeriod`, 7
|
|
522
|
+
days) locks as `unverified`. A network failure inside the grace period keeps it.
|
|
523
|
+
- **While activating** the request is polled every 2 seconds until it lands, fails for good, or is cancelled.
|
|
524
|
+
- **Every 2 seconds**, with no network, the license file is checked for changes made by another instance or process,
|
|
525
|
+
and the license's deadlines are checked: a passed expiry or a grace period that ran out gets one more online check
|
|
526
|
+
before locking. An add-on that runs out changes the state, and so does a day going by on a countdown.
|
|
527
|
+
- **Online checks** are at most every `checkInterval` (5 minutes), and instances sharing the license file take turns,
|
|
528
|
+
so a later one picks up the license an earlier one just refreshed.
|
|
529
|
+
|
|
530
|
+
Every result is gated by a generation counter: a cancel, a new activation or a deactivation supersedes whatever was
|
|
531
|
+
in flight, so a slow response never overwrites a newer state or writes back a license the customer just removed.
|
|
532
|
+
Call `dispose()` to stop watching and polling.
|
|
533
|
+
|
|
534
|
+
Its calls: `activate`, `cancelActivation`, `refresh`, `deactivate`, `forget`, `deviceToken`, `activateOffline`,
|
|
535
|
+
`dismissError`, `device`, `checkUpdate`, `updateDownloadUrl`, `downloadInstaller`, `skipUpdate`, `upgradeLicense`,
|
|
536
|
+
`loadAddOns`, `refreshAddOns`, `activateSubProduct`, `requestSubProductTrial` and `buySubProduct`, with
|
|
537
|
+
`isLicensed()`, `license()` and `hasSubProduct(id)` for gating. A refused call rejects with an `ActivationError`
|
|
538
|
+
whose `kind` is `notLicensed`, `busy` or `internal`, or with the SDK's own `MoonbaseError`. Call `onFocusChanged`
|
|
539
|
+
when the app gains or loses focus, so an add-on bought in the browser unlocks when the customer comes back.
|
|
540
|
+
|
|
541
|
+
`checkUpdate()` uses the SDK's `inventory` client, which reads a release's notes and finds the installer for a
|
|
542
|
+
platform, and `isNewerVersion(current, latest)` compares versions the same way.
|