@moonbase.sh/licensing 3.2.2 → 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 +152 -4
- package/dist/index.cjs +383 -10
- package/dist/index.d.cts +1151 -8
- package/dist/index.d.ts +1151 -8
- package/dist/index.js +379 -10
- package/package.json +3 -2
- package/release-access-vectors.json +150 -0
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,
|
|
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
|
|
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
|