sendclap 0.2.0 → 0.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
@@ -19,7 +19,7 @@ try {
19
19
  settings.instanceId ??= (await licenses.activate(key, await instanceName())).instance_id // first run
20
20
  const r = await licenses.validate(key, settings.instanceId)
21
21
  if (r.valid) settings.lastValidated = Date.now()
22
- else lockApp(r.status) // "invalid" (unknown key), "disabled" (refunded or disputed) or "not_activated"
22
+ else lockApp(r.status) // "not_found" (unknown key), "disabled" (refunded or disputed), "expired" (subscription over) or "not_activated"
23
23
  } catch (e) {
24
24
  // offline: keep working for 7 days after the last successful check
25
25
  if (!(e instanceof NetworkError) || Date.now() - settings.lastValidated > 7 * 86400_000) lockApp('unverified')
@@ -27,7 +27,7 @@ try {
27
27
  ```
28
28
 
29
29
  - `activate(licenseKey, instanceName)` registers this device and returns `{ instance_id, license, product }`. Activating the same instance again counts once, and the instance id is simply the name you passed.
30
- - `validate(licenseKey, instanceId?)` returns `{ valid, status, license?, product? }`. Its `status` is `active`, `not_activated` (the key exists but this device isn't activated), `invalid` (unknown key) or `disabled` (the payment was refunded or disputed). It throws only when no definite answer came back, which is how you tell "offline" from "invalid".
30
+ - `validate(licenseKey, instanceId?)` returns `{ valid, status, license?, product? }`. Its `status` is `active`, `not_activated` (the key exists but this device isn't activated), `expired` (a subscription key past `license.expires_at`), `disabled` (the payment was refunded or disputed) or `not_found` (unknown key). It throws only when no definite answer came back, which is how you tell "offline" from "not found".
31
31
  - `deactivate(licenseKey, instanceId)` frees one activation so the customer can move to another machine. It throws `InstanceNotFoundError` if that instance wasn't activated.
32
32
 
33
33
  To tell a customer why a license doesn't work, branch on the status, or catch the typed error from `activate`:
@@ -35,7 +35,7 @@ To tell a customer why a license doesn't work, branch on the status, or catch th
35
35
  ```ts
36
36
  const r = await licenses.validate(key, instanceId)
37
37
  if (r.status === 'disabled') showMessage('This license was refunded or disputed.')
38
- else if (r.status === 'invalid') showMessage('That license key does not exist.')
38
+ else if (r.status === 'not_found') showMessage('That license key does not exist.')
39
39
 
40
40
  try { await licenses.activate(key, name) } catch (e) {
41
41
  if (e instanceof DisabledLicenseError) showMessage('This license was refunded or disputed.')
@@ -44,7 +44,7 @@ try { await licenses.activate(key, name) } catch (e) {
44
44
 
45
45
  `instanceName()` returns the hostname in Node, Bun, Deno and Electron's main process, and a random id kept in `localStorage` in browsers. The name is sent to Sendclap and shown to the creator in the activity log, and machines that share a hostname share an activation. If that matters, generate your own id (for example `crypto.randomUUID()` saved on first run) and pass it instead.
46
46
 
47
- Cache the result of the last successful `validate` and validate again at startup or once a day. On a `NetworkError`, accept the cached result for a grace period. On `invalid` or `not_activated`, lock.
47
+ Cache the result of the last successful `validate` and validate again at startup or once a day. On a `NetworkError`, accept the cached result for a grace period. On `not_found`, `disabled`, `expired` or `not_activated`, lock.
48
48
 
49
49
  ## Creator API
50
50
 
@@ -79,6 +79,7 @@ Every error is a `SendclapError` with `.status`, `.code` (the server's machine-r
79
79
  | --- | --- | --- |
80
80
  | `InvalidLicenseError` | `license_not_found` | The key doesn't exist (404) |
81
81
  | `DisabledLicenseError` | `license_disabled` | The key was disabled after a refund or a dispute (403) |
82
+ | `ExpiredLicenseError` | `license_expired` | The subscription key has expired, and `.license.expires_at` says when (403) |
82
83
  | `InstanceNotFoundError` | `instance_not_found` | `deactivate` for an instance that isn't activated (404) |
83
84
  | `ActivationLimitError` | `activation_limit` | Every activation is in use, and `.license` shows the counts (409) |
84
85
  | `NetworkError` | `network_error` | No response arrived (offline, DNS, TLS or timeout), and `.status` is 0 |
@@ -1,4 +1,4 @@
1
- export declare const VERSION = "0.2.0";
1
+ export declare const VERSION = "0.4.0";
2
2
  export interface ClientOptions {
3
3
  /** Defaults to https://sendclap.com. */
4
4
  baseUrl?: string;
@@ -23,6 +23,12 @@ export declare class InvalidLicenseError extends SendclapError {
23
23
  export declare class DisabledLicenseError extends SendclapError {
24
24
  constructor(message: string, body?: unknown);
25
25
  }
26
+ /** The subscription license key has expired (`license_expired`); `license.expires_at` says when. */
27
+ export declare class ExpiredLicenseError extends SendclapError {
28
+ readonly license: LicenseInfo;
29
+ readonly product: ProductRef;
30
+ constructor(message: string, license: LicenseInfo, product: ProductRef, body?: unknown);
31
+ }
26
32
  /** Every activation of the key is in use; deactivate another instance first (`activation_limit`). */
27
33
  export declare class ActivationLimitError extends SendclapError {
28
34
  readonly license: LicenseInfo;
@@ -42,6 +48,8 @@ export interface LicenseInfo {
42
48
  key: string;
43
49
  activations: number;
44
50
  max_activations: number;
51
+ /** ISO 8601 time a subscription key expires, or null for a key bought outright. */
52
+ expires_at: string | null;
45
53
  }
46
54
  export interface ProductRef {
47
55
  id?: number;
@@ -58,8 +66,9 @@ export interface DeactivateResult {
58
66
  }
59
67
  export interface ValidateResult {
60
68
  valid: boolean;
61
- /** `active`: valid. `not_activated`: the key exists but this instance isn't activated. `invalid`: unknown key. `disabled`: refunded or disputed. */
62
- status: 'active' | 'not_activated' | 'invalid' | 'disabled';
69
+ /** `active`: valid. `not_activated`: the key exists but this instance isn't activated. `not_found`: unknown key. `expired`: a subscription key past `license.expires_at`. `disabled`: refunded or disputed. */
70
+ status: 'active' | 'not_activated' | 'expired' | 'disabled' | 'not_found';
71
+ /** Present for `active`, `not_activated` and `expired`. */
63
72
  license?: LicenseInfo;
64
73
  product?: ProductRef;
65
74
  }
@@ -84,6 +93,8 @@ export interface Checkout {
84
93
  email: string | null;
85
94
  /** Where to send the customer to pay. */
86
95
  url: string;
96
+ /** ISO 8601 time the checkout was paid, or null while unpaid. */
97
+ paid_at: string | null;
87
98
  }
88
99
  export interface Totals {
89
100
  payments: number;
@@ -104,7 +115,7 @@ export interface Stats {
104
115
  };
105
116
  open_disputes: number;
106
117
  }
107
- /** `limit` is at most 500; `after` is the previous page's `next`. */
118
+ /** `limit` defaults to 50 and is at most 500; `after` is the previous page's `next`. */
108
119
  export interface PageParams {
109
120
  limit?: number;
110
121
  after?: number;
@@ -172,6 +183,7 @@ export interface IssuedLicense {
172
183
  max_activations: number;
173
184
  disabled: boolean;
174
185
  issued_at: string;
186
+ expires_at: string | null;
175
187
  }
176
188
  export interface Dispute {
177
189
  id: string;
@@ -202,6 +214,7 @@ export interface Membership {
202
214
  currency: string;
203
215
  interval: string;
204
216
  x402: string | null;
217
+ license_product_id: number | null;
205
218
  }
206
219
  export interface Creator {
207
220
  handle: string;
@@ -232,7 +245,7 @@ export declare class LicenseClient {
232
245
  private options;
233
246
  constructor(options?: ClientOptions);
234
247
  private call;
235
- /** Registers this device against the key. Throws InvalidLicenseError, DisabledLicenseError or ActivationLimitError. Activating the same instance twice counts once. The returned instance_id is the name you passed. */
248
+ /** Registers this device against the key. Throws InvalidLicenseError, DisabledLicenseError, ExpiredLicenseError or ActivationLimitError. Activating the same instance twice counts once. The returned instance_id is the name you passed. */
236
249
  activate(licenseKey: string, instanceName: string): Promise<ActivateResult>;
237
250
  /** Checks the key (and, with an instance id, that this device is activated). Throws only when no definite answer came back. */
238
251
  validate(licenseKey: string, instanceId?: string): Promise<ValidateResult>;
package/dist/cjs/index.js CHANGED
@@ -35,9 +35,9 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  };
36
36
  })();
37
37
  Object.defineProperty(exports, "__esModule", { value: true });
38
- exports.ApiClient = exports.LicenseClient = exports.NetworkError = exports.InstanceNotFoundError = exports.ActivationLimitError = exports.DisabledLicenseError = exports.InvalidLicenseError = exports.SendclapError = exports.VERSION = void 0;
38
+ exports.ApiClient = exports.LicenseClient = exports.NetworkError = exports.InstanceNotFoundError = exports.ActivationLimitError = exports.ExpiredLicenseError = exports.DisabledLicenseError = exports.InvalidLicenseError = exports.SendclapError = exports.VERSION = void 0;
39
39
  exports.instanceName = instanceName;
40
- exports.VERSION = '0.2.0';
40
+ exports.VERSION = '0.4.0';
41
41
  const DEFAULT_BASE_URL = 'https://sendclap.com';
42
42
  const DEFAULT_TIMEOUT_MS = 15000;
43
43
  // ---------- errors ----------
@@ -71,6 +71,16 @@ class DisabledLicenseError extends SendclapError {
71
71
  }
72
72
  }
73
73
  exports.DisabledLicenseError = DisabledLicenseError;
74
+ /** The subscription license key has expired (`license_expired`); `license.expires_at` says when. */
75
+ class ExpiredLicenseError extends SendclapError {
76
+ constructor(message, license, product, body) {
77
+ super(message, 403, 'license_expired', body);
78
+ this.license = license;
79
+ this.product = product;
80
+ this.name = 'ExpiredLicenseError';
81
+ }
82
+ }
83
+ exports.ExpiredLicenseError = ExpiredLicenseError;
74
84
  /** Every activation of the key is in use; deactivate another instance first (`activation_limit`). */
75
85
  class ActivationLimitError extends SendclapError {
76
86
  constructor(message, license, product, body) {
@@ -139,6 +149,8 @@ async function request(o, method, path, init = {}) {
139
149
  throw new InvalidLicenseError(message, data);
140
150
  if (code === 'license_disabled')
141
151
  throw new DisabledLicenseError(message, data);
152
+ if (code === 'license_expired')
153
+ throw new ExpiredLicenseError(message, data.license, data.product, data);
142
154
  if (code === 'instance_not_found')
143
155
  throw new InstanceNotFoundError(message, data);
144
156
  if (code === 'activation_limit')
@@ -154,24 +166,14 @@ class LicenseClient {
154
166
  call(action, licenseKey, instanceId) {
155
167
  return request(this.options, 'POST', `/licenses/${action}`, { body: { license_key: licenseKey, ...(instanceId ? { instance_id: instanceId } : {}) } });
156
168
  }
157
- /** Registers this device against the key. Throws InvalidLicenseError, DisabledLicenseError or ActivationLimitError. Activating the same instance twice counts once. The returned instance_id is the name you passed. */
169
+ /** Registers this device against the key. Throws InvalidLicenseError, DisabledLicenseError, ExpiredLicenseError or ActivationLimitError. Activating the same instance twice counts once. The returned instance_id is the name you passed. */
158
170
  async activate(licenseKey, instanceName) {
159
171
  const { instance_id, license, product } = await this.call('activate', licenseKey, instanceName);
160
172
  return { instance_id, license, product };
161
173
  }
162
174
  /** Checks the key (and, with an instance id, that this device is activated). Throws only when no definite answer came back. */
163
175
  async validate(licenseKey, instanceId) {
164
- try {
165
- const { valid, license, product } = await this.call('validate', licenseKey, instanceId);
166
- return { valid, status: valid ? 'active' : 'not_activated', license, product };
167
- }
168
- catch (e) {
169
- if (e instanceof InvalidLicenseError)
170
- return { valid: false, status: 'invalid' };
171
- if (e instanceof DisabledLicenseError)
172
- return { valid: false, status: 'disabled' };
173
- throw e;
174
- }
176
+ return this.call('validate', licenseKey, instanceId);
175
177
  }
176
178
  /** Releases a device, freeing one activation. Throws InstanceNotFoundError if it wasn't activated. */
177
179
  async deactivate(licenseKey, instanceId) {
@@ -1,4 +1,4 @@
1
- export declare const VERSION = "0.2.0";
1
+ export declare const VERSION = "0.4.0";
2
2
  export interface ClientOptions {
3
3
  /** Defaults to https://sendclap.com. */
4
4
  baseUrl?: string;
@@ -23,6 +23,12 @@ export declare class InvalidLicenseError extends SendclapError {
23
23
  export declare class DisabledLicenseError extends SendclapError {
24
24
  constructor(message: string, body?: unknown);
25
25
  }
26
+ /** The subscription license key has expired (`license_expired`); `license.expires_at` says when. */
27
+ export declare class ExpiredLicenseError extends SendclapError {
28
+ readonly license: LicenseInfo;
29
+ readonly product: ProductRef;
30
+ constructor(message: string, license: LicenseInfo, product: ProductRef, body?: unknown);
31
+ }
26
32
  /** Every activation of the key is in use; deactivate another instance first (`activation_limit`). */
27
33
  export declare class ActivationLimitError extends SendclapError {
28
34
  readonly license: LicenseInfo;
@@ -42,6 +48,8 @@ export interface LicenseInfo {
42
48
  key: string;
43
49
  activations: number;
44
50
  max_activations: number;
51
+ /** ISO 8601 time a subscription key expires, or null for a key bought outright. */
52
+ expires_at: string | null;
45
53
  }
46
54
  export interface ProductRef {
47
55
  id?: number;
@@ -58,8 +66,9 @@ export interface DeactivateResult {
58
66
  }
59
67
  export interface ValidateResult {
60
68
  valid: boolean;
61
- /** `active`: valid. `not_activated`: the key exists but this instance isn't activated. `invalid`: unknown key. `disabled`: refunded or disputed. */
62
- status: 'active' | 'not_activated' | 'invalid' | 'disabled';
69
+ /** `active`: valid. `not_activated`: the key exists but this instance isn't activated. `not_found`: unknown key. `expired`: a subscription key past `license.expires_at`. `disabled`: refunded or disputed. */
70
+ status: 'active' | 'not_activated' | 'expired' | 'disabled' | 'not_found';
71
+ /** Present for `active`, `not_activated` and `expired`. */
63
72
  license?: LicenseInfo;
64
73
  product?: ProductRef;
65
74
  }
@@ -84,6 +93,8 @@ export interface Checkout {
84
93
  email: string | null;
85
94
  /** Where to send the customer to pay. */
86
95
  url: string;
96
+ /** ISO 8601 time the checkout was paid, or null while unpaid. */
97
+ paid_at: string | null;
87
98
  }
88
99
  export interface Totals {
89
100
  payments: number;
@@ -104,7 +115,7 @@ export interface Stats {
104
115
  };
105
116
  open_disputes: number;
106
117
  }
107
- /** `limit` is at most 500; `after` is the previous page's `next`. */
118
+ /** `limit` defaults to 50 and is at most 500; `after` is the previous page's `next`. */
108
119
  export interface PageParams {
109
120
  limit?: number;
110
121
  after?: number;
@@ -172,6 +183,7 @@ export interface IssuedLicense {
172
183
  max_activations: number;
173
184
  disabled: boolean;
174
185
  issued_at: string;
186
+ expires_at: string | null;
175
187
  }
176
188
  export interface Dispute {
177
189
  id: string;
@@ -202,6 +214,7 @@ export interface Membership {
202
214
  currency: string;
203
215
  interval: string;
204
216
  x402: string | null;
217
+ license_product_id: number | null;
205
218
  }
206
219
  export interface Creator {
207
220
  handle: string;
@@ -232,7 +245,7 @@ export declare class LicenseClient {
232
245
  private options;
233
246
  constructor(options?: ClientOptions);
234
247
  private call;
235
- /** Registers this device against the key. Throws InvalidLicenseError, DisabledLicenseError or ActivationLimitError. Activating the same instance twice counts once. The returned instance_id is the name you passed. */
248
+ /** Registers this device against the key. Throws InvalidLicenseError, DisabledLicenseError, ExpiredLicenseError or ActivationLimitError. Activating the same instance twice counts once. The returned instance_id is the name you passed. */
236
249
  activate(licenseKey: string, instanceName: string): Promise<ActivateResult>;
237
250
  /** Checks the key (and, with an instance id, that this device is activated). Throws only when no definite answer came back. */
238
251
  validate(licenseKey: string, instanceId?: string): Promise<ValidateResult>;
package/dist/esm/index.js CHANGED
@@ -1,6 +1,6 @@
1
1
  // Sendclap client for JavaScript and TypeScript: license checks for the apps you ship, and the creator REST API for your server.
2
2
  // Zero dependencies; uses the global fetch (Node 18+, Bun, Deno, browsers, Electron).
3
- export const VERSION = '0.2.0';
3
+ export const VERSION = '0.4.0';
4
4
  const DEFAULT_BASE_URL = 'https://sendclap.com';
5
5
  const DEFAULT_TIMEOUT_MS = 15000;
6
6
  // ---------- errors ----------
@@ -31,6 +31,15 @@ export class DisabledLicenseError extends SendclapError {
31
31
  this.name = 'DisabledLicenseError';
32
32
  }
33
33
  }
34
+ /** The subscription license key has expired (`license_expired`); `license.expires_at` says when. */
35
+ export class ExpiredLicenseError extends SendclapError {
36
+ constructor(message, license, product, body) {
37
+ super(message, 403, 'license_expired', body);
38
+ this.license = license;
39
+ this.product = product;
40
+ this.name = 'ExpiredLicenseError';
41
+ }
42
+ }
34
43
  /** Every activation of the key is in use; deactivate another instance first (`activation_limit`). */
35
44
  export class ActivationLimitError extends SendclapError {
36
45
  constructor(message, license, product, body) {
@@ -96,6 +105,8 @@ async function request(o, method, path, init = {}) {
96
105
  throw new InvalidLicenseError(message, data);
97
106
  if (code === 'license_disabled')
98
107
  throw new DisabledLicenseError(message, data);
108
+ if (code === 'license_expired')
109
+ throw new ExpiredLicenseError(message, data.license, data.product, data);
99
110
  if (code === 'instance_not_found')
100
111
  throw new InstanceNotFoundError(message, data);
101
112
  if (code === 'activation_limit')
@@ -111,24 +122,14 @@ export class LicenseClient {
111
122
  call(action, licenseKey, instanceId) {
112
123
  return request(this.options, 'POST', `/licenses/${action}`, { body: { license_key: licenseKey, ...(instanceId ? { instance_id: instanceId } : {}) } });
113
124
  }
114
- /** Registers this device against the key. Throws InvalidLicenseError, DisabledLicenseError or ActivationLimitError. Activating the same instance twice counts once. The returned instance_id is the name you passed. */
125
+ /** Registers this device against the key. Throws InvalidLicenseError, DisabledLicenseError, ExpiredLicenseError or ActivationLimitError. Activating the same instance twice counts once. The returned instance_id is the name you passed. */
115
126
  async activate(licenseKey, instanceName) {
116
127
  const { instance_id, license, product } = await this.call('activate', licenseKey, instanceName);
117
128
  return { instance_id, license, product };
118
129
  }
119
130
  /** Checks the key (and, with an instance id, that this device is activated). Throws only when no definite answer came back. */
120
131
  async validate(licenseKey, instanceId) {
121
- try {
122
- const { valid, license, product } = await this.call('validate', licenseKey, instanceId);
123
- return { valid, status: valid ? 'active' : 'not_activated', license, product };
124
- }
125
- catch (e) {
126
- if (e instanceof InvalidLicenseError)
127
- return { valid: false, status: 'invalid' };
128
- if (e instanceof DisabledLicenseError)
129
- return { valid: false, status: 'disabled' };
130
- throw e;
131
- }
132
+ return this.call('validate', licenseKey, instanceId);
132
133
  }
133
134
  /** Releases a device, freeing one activation. Throws InstanceNotFoundError if it wasn't activated. */
134
135
  async deactivate(licenseKey, instanceId) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sendclap",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "description": "Official Sendclap client: license key checks for the apps you ship and the creator REST API.",
5
5
  "license": "MIT",
6
6
  "repository": { "type": "git", "url": "git+https://github.com/backmeupplz/sendclap-sdk.git", "directory": "js" },