@moonbase.sh/licensing 3.2.3 → 3.3.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
@@ -65,12 +65,14 @@ such as opening the app offline.
65
65
 
66
66
  ```ts
67
67
  import type { License } from '@moonbase.sh/licensing'
68
- import { ActivationMethod, ErrorType, MoonbaseError } from '@moonbase.sh/licensing'
68
+ import { ActivationMethod, ErrorType, MoonbaseError, ReleaseNotCoveredError } from '@moonbase.sh/licensing'
69
69
 
70
70
  // Moonbase says the license can no longer be used on this device. Anything
71
71
  // 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).
72
+ // MoonbaseError), only means Moonbase could not be reached right now,
73
+ // ErrorType.StoreClosed that it never will be again (see below), and
74
+ // ErrorType.ReleaseNotCovered that the license is good, just not for this
75
+ // version of the app (see "Licenses that cover some versions").
74
76
  const licenseGone = new Set<ErrorType | undefined>([
75
77
  ErrorType.LicenseRevoked,
76
78
  ErrorType.LicenseActivationRevoked,
@@ -93,6 +95,14 @@ async function licenseOnStartup(): Promise<License | null> {
93
95
  return refreshed
94
96
  }
95
97
  catch (err) {
98
+ if (err instanceof ReleaseNotCoveredError) {
99
+ // Still the customer's license, for the versions it covers: keep the
100
+ // fresh copy Moonbase sent along
101
+ if (err.license)
102
+ await licensing.store.storeLocalLicense(err.license)
103
+ offerUpgrade(err)
104
+ return null
105
+ }
96
106
  if (err instanceof MoonbaseError && licenseGone.has(err.type)) {
97
107
  await licensing.store.deleteLocalLicense()
98
108
  return null // show your activation flow
@@ -103,12 +113,16 @@ async function licenseOnStartup(): Promise<License | null> {
103
113
  }
104
114
 
105
115
  try {
106
- // Signature, device binding and expiry, which needs no network
116
+ // Signature, device binding, expiry and the app version, which needs no network
107
117
  return await licensing.validator.validateLicense(localLicense.token)
108
118
  }
109
119
  catch (err) {
110
120
  // Keep the stored token: only Moonbase can say the license is gone, and the
111
121
  // next launch that reaches it can still refresh a token that has expired
122
+ if (err instanceof ReleaseNotCoveredError) {
123
+ offerUpgrade(err)
124
+ return null
125
+ }
112
126
  if (err instanceof MoonbaseError)
113
127
  return null // show your activation flow
114
128
  throw err
@@ -145,6 +159,7 @@ license makes a device independent of Moonbase.
145
159
  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
160
 
147
161
  - `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`.
162
+ - `appVersion` is also the version a license has to cover, for a license that covers only some versions (see below).
148
163
  - `platform` auto-detects from `process.platform` (`darwin` → `Mac`, `win32` → `Windows`, `linux` → `Linux`). Set it explicitly to override, or pass `null` to suppress.
149
164
  - All three are sent on `requestActivation`, `requestTrial`, and `validateLicense`, never on `revokeLicense`.
150
165
  - `metadata` accepts string keys and string values only; empty values are dropped client-side.
@@ -152,6 +167,139 @@ The SDK can report analytics with every activation, trial request, and validatio
152
167
  - 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
168
  - Keep payloads small; query-string length limits apply.
154
169
 
170
+ ## Licenses that cover some versions
171
+
172
+ A license bought outright can cover only some versions of the app: those released during its updates ("12 months
173
+ of updates"), or every version up to a major ("versions up to 2.x"). The license itself never expires; it just
174
+ doesn't cover the versions after that. It says what it covers in `releaseAccess`, which is absent when it covers
175
+ every version:
176
+
177
+ - `updatesUntil`: releases published until then are covered, and every version while it has not passed.
178
+ - `upToMajor`: every version whose major is at most this is covered.
179
+ - `upToVersion`: once updates have ended, the last version published before they did, covered along with every
180
+ older one. Absent while updates last, and when nothing was published before they ended (then every version is
181
+ covered).
182
+
183
+ The limits add up: a license with both covers a version that either covers.
184
+
185
+ Set `appVersion` for the version to be checked. Activating or validating a license that doesn't cover it throws a
186
+ `ReleaseNotCoveredError` (`ErrorType.ReleaseNotCovered`), and so does `validator.validateLicense` on the device,
187
+ judged by the device clock. Set `enforceReleaseAccess: false` to turn the check on the device off; Moonbase checks
188
+ online activation and validation either way. A license activated offline, from a device token the customer brings to
189
+ 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`,
190
+ then two to four numbers (a fourth is ignored), with any `-beta` or `+build` suffix dropped, so `3.0.0-beta.2` is
191
+ judged as 3.0.0.
192
+
193
+ Do not delete the stored license on `ReleaseNotCoveredError`, and do not treat it like a revoked one: it still covers
194
+ the versions it did, so the customer can go back to one of them, or upgrade and keep going. Validating online sends
195
+ the license along, freshly issued, in `err.license`, to store in place of the old one. Say what the license covers
196
+ and offer the upgrade:
197
+
198
+ ```ts
199
+ function offerUpgrade(err: ReleaseNotCoveredError) {
200
+ const access = err.releaseAccess
201
+ const coversUpTo = access?.upToVersion
202
+ ?? (access?.upToMajor !== undefined ? `${access.upToMajor}.x` : undefined)
203
+
204
+ showUpgradeDialog({
205
+ message: coversUpTo
206
+ ? `Your license covers versions up to ${coversUpTo}, not ${err.appVersion}.`
207
+ : `Your license doesn't cover version ${err.appVersion}.`,
208
+ // Where the customer buys the upgrade. Only Moonbase knows it, so it is
209
+ // absent when the check on the device refused.
210
+ upgradeUrl: err.upgradeUrl,
211
+ })
212
+ }
213
+ ```
214
+
215
+ To check another version, such as an update before offering to download it, use `coversVersion`:
216
+
217
+ ```ts
218
+ import { coversVersion } from '@moonbase.sh/licensing'
219
+
220
+ if (!coversVersion(license, latestRelease.version)) {
221
+ // offer the upgrade along with the update
222
+ }
223
+ ```
224
+
225
+ `coversVersion(license, version, now = new Date())` applies the same rule as Moonbase and every other Moonbase
226
+ SDK. The shipped [`release-access-vectors.json`](./release-access-vectors.json) pins it down case by case, and
227
+ `parseAppVersion` reads a version the way it does.
228
+
229
+ ## Add-ons
230
+
231
+ An add-on (a sub-product, with a product ID like `my-app.strings`) that the merchant includes in its main
232
+ product's license travels in the main license, so one validation answers for both. When a device activates or
233
+ validates the main product, it takes a seat of each such add-on the customer owns, and the license lists them in
234
+ `subProducts`:
235
+
236
+ ```ts
237
+ import { hasSubProduct } from '@moonbase.sh/licensing'
238
+
239
+ if (hasSubProduct(license, 'strings')) {
240
+ // unlock the strings add-on
241
+ }
242
+ ```
243
+
244
+ `hasSubProduct` takes the add-on's own part of its ID or the whole ID. It is true while the license lists the
245
+ add-on as active and it has not expired, which matters for an offline license. An add-on the customer owns, but
246
+ with every seat taken on other devices, is listed with `active: false`. An add-on bought after the device activated
247
+ shows up at the next `validateLicense`.
248
+
249
+ If the customer revokes an add-on's seat on this device (from their account, or the merchant does it for them),
250
+ validating does not take it back: the license lists it with `revoked: true` until the app activates it again. To
251
+ activate add-ons yourself instead of on every activation and validation, set `autoActivateSubProducts: false`.
252
+ Either way, take a seat with:
253
+
254
+ ```ts
255
+ const license = await licensing.client.activateSubProduct(localLicense, 'strings')
256
+ await licensing.store.storeLocalLicense(license)
257
+ ```
258
+
259
+ It throws `ErrorType.NoEligibleLicense` when the customer doesn't own the add-on or has no free seat of it.
260
+
261
+ To let a customer try an add-on that offers trials, start its trial from the main license and store what comes
262
+ back in its place:
263
+
264
+ ```ts
265
+ const license = await licensing.client.requestSubProductTrial(localLicense, 'strings')
266
+ await licensing.store.storeLocalLicense(license)
267
+ ```
268
+
269
+ The license must be an online license, not a trial. A customer who owns the add-on gets a seat of it instead, as
270
+ `activateSubProduct` does, and a device gets one trial of each add-on: asking again returns the license with the
271
+ trial it had, expired or not.
272
+ Revoking the main license's activation frees the device's add-on seats too.
273
+
274
+ `ownedSubProductIds` still lists every add-on the customer owns, included in the license or not, without saying
275
+ whether it may be used on this device.
276
+
277
+ To show the customer what else there is, for example on an upgrade screen, list the product's add-ons from the
278
+ license (or a trial) the device holds. Each comes with its prices when it is for sale, whether the customer owns it,
279
+ whether to unlock it here, and its trial:
280
+
281
+ ```ts
282
+ const { currency, subProducts } = await licensing.client.listSubProducts(localLicense)
283
+
284
+ for (const addOn of subProducts) {
285
+ const price = addOn.product.defaultVariation?.price[currency]
286
+ if (addOn.active) {
287
+ // owned, or trialing, on this device
288
+ }
289
+ else if (addOn.trial?.status === 'Available') {
290
+ // offer "Try it", which calls requestSubProductTrial
291
+ }
292
+ else if (addOn.buyUrl) {
293
+ // offer "Buy" for `price`, opening addOn.buyUrl in the browser
294
+ }
295
+ }
296
+ ```
297
+
298
+ It lists only the add-ons the customer can do something with: ones they own or subscribe to, ones on sale, and ones
299
+ whose trial can be started or is running on this device. `trial.status` is `Available` when
300
+ `requestSubProductTrial` can start one now, `Active` or `Expired` for the trial the device had, and `Unavailable`
301
+ otherwise. Listing changes nothing.
302
+
155
303
  ## Revoke a license activation
156
304
 
157
305
  ```ts