@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 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, and
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 expiry, which needs no network
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.