sendclap 0.2.0__tar.gz → 0.4.0__tar.gz

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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: sendclap
3
- Version: 0.2.0
3
+ Version: 0.4.0
4
4
  Summary: Official Sendclap client: license key checks for your app and the creator REST API
5
5
  Project-URL: Homepage, https://sendclap.com
6
6
  Project-URL: Documentation, https://sendclap.com/docs
@@ -32,7 +32,7 @@ def licensed(key: str, cache: dict) -> bool:
32
32
  return time.time() - cache.get("validated_at", 0) < 7 * 86400
33
33
  if r.valid:
34
34
  cache["validated_at"] = time.time() # persist cache to disk yourself
35
- return r.valid # status "invalid", "disabled" or "not_activated": lock the app
35
+ return r.valid # status "not_found", "disabled", "expired" or "not_activated": lock the app
36
36
  ```
37
37
 
38
38
  On first run, activate the device and remember the instance id:
@@ -46,7 +46,7 @@ except DisabledLicenseError: ... # the payment was refunded or disputed
46
46
  except ActivationLimitError as e: print(f"Used on {e.license.activations}/{e.license.max_activations} devices")
47
47
  ```
48
48
 
49
- `deactivate(key, instance_id)` frees the device again, and raises `InstanceNotFoundError` if it wasn't activated. `validate` never raises for a bad key; it returns `status` `"active"`, `"not_activated"`, `"invalid"` (unknown key) or `"disabled"` (refunded or disputed), and raises `NetworkError` only when it could not reach Sendclap, so you can tell "offline" from "invalid" and show "this license was refunded" for `"disabled"`.
49
+ `deactivate(key, instance_id)` frees the device again, and raises `InstanceNotFoundError` if it wasn't activated. `validate` never raises for a bad key; it returns `status` `"active"`, `"not_activated"`, `"expired"` (subscription over, see `license.expires_at`), `"disabled"` (refunded or disputed) or `"not_found"` (unknown key), and raises `NetworkError` only when it could not reach Sendclap, so you can tell "offline" from "not found" and show "this license was refunded" for `"disabled"`.
50
50
 
51
51
  **Instance name:** `instance_name()` is the machine's hostname. It is sent to Sendclap and shown to the creator, and two machines with the same hostname share one activation. If that matters, pass your own stable id instead (for example a `uuid4()` saved on first run). The instance id Sendclap returns is the name you send.
52
52
 
@@ -68,7 +68,7 @@ for p in api.all_payments(status="paid"): # a generator that follows `next` acr
68
68
  print(p["amount"], p["email"])
69
69
  ```
70
70
 
71
- Lists (`list_payments`, `list_members`, `list_licenses`, `list_disputes`) return a `Page` with `data`, `has_more` and `next`, newest first; `limit` is at most 500 and `after` is the previous page's `next`. `all_payments`, `all_members`, `all_licenses` and `all_disputes` take the same filters and yield every item.
71
+ Lists (`list_payments`, `list_members`, `list_licenses`, `list_disputes`) return a `Page` with `data`, `has_more` and `next`, newest first; `limit` defaults to 50 and is at most 500 and `after` is the previous page's `next`. `all_payments`, `all_members`, `all_licenses` and `all_disputes` take the same filters and yield every item.
72
72
 
73
73
  Methods: `create_checkout` and `get_checkout` (both return the checkout `url`), `me`, `get_payment`, `list_products`, `list_memberships`, the list and `all_*` methods above, and `get_creator` (public, works with `ApiClient()` and no key). Items are plain dicts with the API's JSON fields, typed with `TypedDict`.
74
74
 
@@ -82,6 +82,7 @@ Every exception is a `SendclapError` with `.status`, `.code` (the server's machi
82
82
  |---|---|---|
83
83
  | `InvalidLicenseError` | `license_not_found` | 404: the key doesn't exist |
84
84
  | `DisabledLicenseError` | `license_disabled` | 403: disabled after a refund or dispute |
85
+ | `ExpiredLicenseError` | `license_expired` | 403: the subscription key expired; `.license.expires_at` says when |
85
86
  | `InstanceNotFoundError` | `instance_not_found` | 404: `deactivate` for an instance that isn't activated |
86
87
  | `ActivationLimitError` | `activation_limit` | 409: every activation is used; `.license` and `.product` say how many |
87
88
  | `NetworkError` | `network_error` | No response: offline, DNS, TLS, timeout (`.status == 0`) |
@@ -19,7 +19,7 @@ def licensed(key: str, cache: dict) -> bool:
19
19
  return time.time() - cache.get("validated_at", 0) < 7 * 86400
20
20
  if r.valid:
21
21
  cache["validated_at"] = time.time() # persist cache to disk yourself
22
- return r.valid # status "invalid", "disabled" or "not_activated": lock the app
22
+ return r.valid # status "not_found", "disabled", "expired" or "not_activated": lock the app
23
23
  ```
24
24
 
25
25
  On first run, activate the device and remember the instance id:
@@ -33,7 +33,7 @@ except DisabledLicenseError: ... # the payment was refunded or disputed
33
33
  except ActivationLimitError as e: print(f"Used on {e.license.activations}/{e.license.max_activations} devices")
34
34
  ```
35
35
 
36
- `deactivate(key, instance_id)` frees the device again, and raises `InstanceNotFoundError` if it wasn't activated. `validate` never raises for a bad key; it returns `status` `"active"`, `"not_activated"`, `"invalid"` (unknown key) or `"disabled"` (refunded or disputed), and raises `NetworkError` only when it could not reach Sendclap, so you can tell "offline" from "invalid" and show "this license was refunded" for `"disabled"`.
36
+ `deactivate(key, instance_id)` frees the device again, and raises `InstanceNotFoundError` if it wasn't activated. `validate` never raises for a bad key; it returns `status` `"active"`, `"not_activated"`, `"expired"` (subscription over, see `license.expires_at`), `"disabled"` (refunded or disputed) or `"not_found"` (unknown key), and raises `NetworkError` only when it could not reach Sendclap, so you can tell "offline" from "not found" and show "this license was refunded" for `"disabled"`.
37
37
 
38
38
  **Instance name:** `instance_name()` is the machine's hostname. It is sent to Sendclap and shown to the creator, and two machines with the same hostname share one activation. If that matters, pass your own stable id instead (for example a `uuid4()` saved on first run). The instance id Sendclap returns is the name you send.
39
39
 
@@ -55,7 +55,7 @@ for p in api.all_payments(status="paid"): # a generator that follows `next` acr
55
55
  print(p["amount"], p["email"])
56
56
  ```
57
57
 
58
- Lists (`list_payments`, `list_members`, `list_licenses`, `list_disputes`) return a `Page` with `data`, `has_more` and `next`, newest first; `limit` is at most 500 and `after` is the previous page's `next`. `all_payments`, `all_members`, `all_licenses` and `all_disputes` take the same filters and yield every item.
58
+ Lists (`list_payments`, `list_members`, `list_licenses`, `list_disputes`) return a `Page` with `data`, `has_more` and `next`, newest first; `limit` defaults to 50 and is at most 500 and `after` is the previous page's `next`. `all_payments`, `all_members`, `all_licenses` and `all_disputes` take the same filters and yield every item.
59
59
 
60
60
  Methods: `create_checkout` and `get_checkout` (both return the checkout `url`), `me`, `get_payment`, `list_products`, `list_memberships`, the list and `all_*` methods above, and `get_creator` (public, works with `ApiClient()` and no key). Items are plain dicts with the API's JSON fields, typed with `TypedDict`.
61
61
 
@@ -69,6 +69,7 @@ Every exception is a `SendclapError` with `.status`, `.code` (the server's machi
69
69
  |---|---|---|
70
70
  | `InvalidLicenseError` | `license_not_found` | 404: the key doesn't exist |
71
71
  | `DisabledLicenseError` | `license_disabled` | 403: disabled after a refund or dispute |
72
+ | `ExpiredLicenseError` | `license_expired` | 403: the subscription key expired; `.license.expires_at` says when |
72
73
  | `InstanceNotFoundError` | `instance_not_found` | 404: `deactivate` for an instance that isn't activated |
73
74
  | `ActivationLimitError` | `activation_limit` | 409: every activation is used; `.license` and `.product` say how many |
74
75
  | `NetworkError` | `network_error` | No response: offline, DNS, TLS, timeout (`.status == 0`) |
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "sendclap"
7
- version = "0.2.0"
7
+ version = "0.4.0"
8
8
  description = "Official Sendclap client: license key checks for your app and the creator REST API"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -9,13 +9,13 @@ import urllib.request
9
9
  from dataclasses import dataclass
10
10
  from typing import Any, Callable, Dict, Generic, Iterator, List, Optional, TypedDict, TypeVar
11
11
 
12
- __version__ = "0.2.0"
12
+ __version__ = "0.4.0"
13
13
  DEFAULT_BASE_URL = "https://sendclap.com"
14
14
  USER_AGENT = f"sendclap-python/{__version__}"
15
15
 
16
16
  __all__ = [
17
17
  "LicenseClient", "ApiClient", "instance_name",
18
- "SendclapError", "InvalidLicenseError", "DisabledLicenseError", "InstanceNotFoundError",
18
+ "SendclapError", "InvalidLicenseError", "DisabledLicenseError", "ExpiredLicenseError", "InstanceNotFoundError",
19
19
  "ActivationLimitError", "NetworkError",
20
20
  "ActivateResult", "ValidateResult", "DeactivateResult", "LicenseInfo", "ProductRef",
21
21
  "Page", "Checkout", "Totals", "Stats", "Payment", "PaymentDetail", "Member", "IssuedLicense",
@@ -48,6 +48,15 @@ class DisabledLicenseError(SendclapError):
48
48
  """The key exists but was disabled after a refund or dispute (license_disabled)."""
49
49
 
50
50
 
51
+ class ExpiredLicenseError(SendclapError):
52
+ """The subscription license key has expired (license_expired); license.expires_at says when."""
53
+
54
+ def __init__(self, status: int, message: str, license: LicenseInfo, product: ProductRef) -> None:
55
+ super().__init__(status, message, "license_expired")
56
+ self.license = license
57
+ self.product = product
58
+
59
+
51
60
  class InstanceNotFoundError(SendclapError):
52
61
  """Deactivate was called for an instance that isn't activated (instance_not_found)."""
53
62
 
@@ -75,6 +84,7 @@ class LicenseInfo:
75
84
  key: str
76
85
  activations: int
77
86
  max_activations: int
87
+ expires_at: Optional[str] = None # ISO 8601 time a subscription key expires, None if bought outright
78
88
 
79
89
 
80
90
  @dataclass(frozen=True)
@@ -93,7 +103,7 @@ class ActivateResult:
93
103
  @dataclass(frozen=True)
94
104
  class ValidateResult:
95
105
  valid: bool
96
- status: str # "active", "not_activated", "invalid" (unknown key) or "disabled" (refunded or disputed)
106
+ status: str # "active", "not_activated", "expired" (subscription over), "disabled" (refunded or disputed) or "not_found" (unknown key)
97
107
  license: Optional[LicenseInfo] = None
98
108
  product: Optional[ProductRef] = None
99
109
 
@@ -115,6 +125,7 @@ class Checkout(TypedDict):
115
125
  method: str
116
126
  email: Optional[str]
117
127
  url: str # where to send the customer to pay
128
+ paid_at: Optional[str] # ISO 8601 time it was paid, None while unpaid
118
129
 
119
130
 
120
131
  T = TypeVar("T")
@@ -188,6 +199,7 @@ class IssuedLicense(TypedDict):
188
199
  max_activations: int
189
200
  disabled: bool
190
201
  issued_at: str
202
+ expires_at: Optional[str]
191
203
 
192
204
 
193
205
  class Dispute(TypedDict):
@@ -211,6 +223,7 @@ class Product(TypedDict):
211
223
  issues_license_key: bool
212
224
  page: str
213
225
  x402: Optional[str]
226
+ license_product_id: Optional[int]
214
227
 
215
228
 
216
229
  class Membership(TypedDict):
@@ -281,6 +294,8 @@ class _Http:
281
294
  raise InvalidLicenseError(status, msg, code)
282
295
  if code == "license_disabled":
283
296
  raise DisabledLicenseError(status, msg, code)
297
+ if code == "license_expired":
298
+ raise ExpiredLicenseError(status, msg, _license(d), _product(d))
284
299
  if code == "instance_not_found":
285
300
  raise InstanceNotFoundError(status, msg, code)
286
301
  if code == "activation_limit":
@@ -291,7 +306,7 @@ class _Http:
291
306
  def _license(d: Dict[str, Any]) -> LicenseInfo:
292
307
  lic = d.get("license") or {}
293
308
  return LicenseInfo(key=lic.get("key", ""), activations=lic.get("activations", 0),
294
- max_activations=lic.get("max_activations", 0))
309
+ max_activations=lic.get("max_activations", 0), expires_at=lic.get("expires_at"))
295
310
 
296
311
 
297
312
  def _product(d: Dict[str, Any]) -> ProductRef:
@@ -325,16 +340,11 @@ class LicenseClient:
325
340
  return ActivateResult(instance_id=d["instance_id"], license=_license(d), product=_product(d))
326
341
 
327
342
  def validate(self, license_key: str, instance_id: Optional[str] = None) -> ValidateResult:
328
- """Never raises for a bad key: returns status "invalid" or "disabled". Raises NetworkError when offline."""
329
- try:
330
- d = self._post("validate", license_key, instance_id)
331
- except InvalidLicenseError:
332
- return ValidateResult(valid=False, status="invalid")
333
- except DisabledLicenseError:
334
- return ValidateResult(valid=False, status="disabled")
335
- valid = d.get("valid") is True
336
- return ValidateResult(valid=valid, status="active" if valid else "not_activated",
337
- license=_license(d), product=_product(d))
343
+ """Never raises for a bad key: returns status "not_found", "disabled" or "expired". Raises NetworkError when offline."""
344
+ d = self._post("validate", license_key, instance_id)
345
+ known = "license" in d
346
+ return ValidateResult(valid=d.get("valid") is True, status=d["status"],
347
+ license=_license(d) if known else None, product=_product(d) if known else None)
338
348
 
339
349
  def deactivate(self, license_key: str, instance_id: str) -> DeactivateResult:
340
350
  d = self._post("deactivate", license_key, instance_id)
@@ -378,7 +388,7 @@ class ApiClient:
378
388
  d = self._http.request("GET", path, query=query)
379
389
  return Page(data=d["data"], has_more=d["has_more"], next=d["next"])
380
390
 
381
- # Lists are pages: `limit` is at most 500, `after` is the previous page's `next`. The all_* generators follow `next`.
391
+ # Lists are pages: `limit` defaults to 50 and is at most 500, `after` is the previous page's `next`. The all_* generators follow `next`.
382
392
  def list_payments(self, status: Optional[str] = None, type: Optional[str] = None, email: Optional[str] = None,
383
393
  limit: Optional[int] = None, after: Optional[int] = None) -> Page[Payment]:
384
394
  return self._page("/payments", {"status": status, "type": type, "email": email, "limit": limit, "after": after})
@@ -10,14 +10,15 @@ sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
10
10
 
11
11
  import sendclap # noqa: E402
12
12
  from sendclap import ( # noqa: E402
13
- ActivationLimitError, ApiClient, DisabledLicenseError, InstanceNotFoundError, InvalidLicenseError,
13
+ ActivationLimitError, ApiClient, DisabledLicenseError, ExpiredLicenseError, InstanceNotFoundError, InvalidLicenseError,
14
14
  LicenseClient, NetworkError, SendclapError,
15
15
  )
16
16
 
17
17
  LICENSE = {"key": "GOOD", "activations": 1, "max_activations": 3}
18
18
  PRODUCT = {"id": 1, "name": "Pro"}
19
+ LAPSED = {**LICENSE, "expires_at": "2026-01-01T00:00:00.000Z"}
19
20
  CHECKOUT = {"id": "0xabc", "status": "pending", "type": "product", "amount": 29, "currency": "usd",
20
- "method": "card", "email": "buyer@example.com", "url": "http://x/checkout/0xabc"}
21
+ "method": "card", "email": "buyer@example.com", "url": "http://x/checkout/0xabc", "paid_at": None}
21
22
  PAYMENTS = [{"id": 3, "status": "paid"}, {"id": 2, "status": "paid"}, {"id": 1, "status": "paid"}]
22
23
  SEEN = [] # (method, path, headers, body) of every request
23
24
 
@@ -42,22 +43,32 @@ class Mock(BaseHTTPRequestHandler):
42
43
  p = url.path
43
44
  if p.startswith("/api/v1/licenses/"):
44
45
  action, key, inst = p.rsplit("/", 1)[1], body.get("license_key"), body.get("instance_id")
45
- if key == "REFUNDED":
46
- return self.reply(403, {"valid": False, "error": "this license key is disabled", "code": "license_disabled"})
47
- if key != "GOOD" and key != "FULL":
48
- return self.reply(404, {"valid": False, "error": "license key not found", "code": "license_not_found"})
49
46
  if action == "validate":
50
- return self.reply(200, {"valid": inst in (None, "dev-1"), "license": LICENSE, "product": PRODUCT})
47
+ if key == "REFUNDED":
48
+ return self.reply(200, {"valid": False, "status": "disabled"})
49
+ if key == "LAPSED":
50
+ return self.reply(200, {"valid": False, "status": "expired", "license": LAPSED, "product": PRODUCT})
51
+ if key not in ("GOOD", "FULL"):
52
+ return self.reply(200, {"valid": False, "status": "not_found"})
53
+ ok = inst in (None, "dev-1")
54
+ return self.reply(200, {"valid": ok, "status": "active" if ok else "not_activated",
55
+ "license": LICENSE, "product": PRODUCT})
56
+ if key == "REFUNDED":
57
+ return self.reply(403, {"error": "this license key is disabled", "code": "license_disabled"})
58
+ if key == "LAPSED":
59
+ return self.reply(403, {"error": "this license key has expired", "code": "license_expired",
60
+ "license": LAPSED, "product": PRODUCT})
61
+ if key not in ("GOOD", "FULL"):
62
+ return self.reply(404, {"error": "license key not found", "code": "license_not_found"})
51
63
  if not inst:
52
64
  return self.reply(400, {"error": "instance_id is required", "code": "bad_request"})
53
65
  if action == "activate" and key == "FULL":
54
- return self.reply(409, {"activated": False, "error": "activation limit reached", "code": "activation_limit",
66
+ return self.reply(409, {"error": "activation limit reached", "code": "activation_limit",
55
67
  "license": {"key": "FULL", "activations": 3, "max_activations": 3}, "product": PRODUCT})
56
68
  if action == "activate":
57
69
  return self.reply(200, {"activated": True, "instance_id": inst, "license": LICENSE, "product": PRODUCT})
58
70
  if inst != "dev-1":
59
- return self.reply(404, {"deactivated": False, "error": "that instance is not activated",
60
- "code": "instance_not_found", "license": LICENSE, "product": PRODUCT})
71
+ return self.reply(404, {"error": "that instance is not activated", "code": "instance_not_found"})
61
72
  return self.reply(200, {"deactivated": True, "license": dict(LICENSE, activations=0), "product": PRODUCT})
62
73
  if p == "/api/v1/creators/demo":
63
74
  return self.reply(200, {"handle": "demo", "name": "Ada Builds"})
@@ -67,6 +78,8 @@ class Mock(BaseHTTPRequestHandler):
67
78
  return self.reply(201, CHECKOUT)
68
79
  if p == "/api/v1/checkouts/0xabc":
69
80
  return self.reply(200, CHECKOUT)
81
+ if p == "/api/v1/checkouts/0xpaid":
82
+ return self.reply(200, dict(CHECKOUT, status="paid", paid_at="2026-11-14T10:00:00.000Z"))
70
83
  if p == "/api/v1/payments": # two per page, newest first, cursor = the last id on the page
71
84
  after = int(parse_qs(url.query).get("after", ["1000"])[0])
72
85
  rows = [r for r in PAYMENTS if r["id"] < after]
@@ -111,7 +124,7 @@ class SendclapTest(unittest.TestCase):
111
124
  method, path, headers, body = SEEN[-1]
112
125
  self.assertEqual((method, path), ("POST", "/api/v1/licenses/activate"))
113
126
  self.assertEqual(body, {"license_key": "GOOD", "instance_id": "dev-1"})
114
- self.assertEqual(headers["User-Agent"], "sendclap-python/0.2.0")
127
+ self.assertEqual(headers["User-Agent"], "sendclap-python/0.4.0")
115
128
  self.assertEqual(headers["Content-Type"], "application/json")
116
129
  self.assertNotIn("Authorization", headers)
117
130
 
@@ -135,6 +148,14 @@ class SendclapTest(unittest.TestCase):
135
148
  self.assertNotIsInstance(cm.exception, InvalidLicenseError)
136
149
  self.assertEqual((cm.exception.status, cm.exception.code), (403, "license_disabled"))
137
150
 
151
+ def test_expired_key(self):
152
+ r = self.lic.validate("LAPSED", "dev-1")
153
+ self.assertEqual((r.valid, r.status, r.license.expires_at, r.product.name), (False, "expired", "2026-01-01T00:00:00.000Z", "Pro"))
154
+ with self.assertRaises(ExpiredLicenseError) as cm:
155
+ self.lic.activate("LAPSED", "dev-1")
156
+ self.assertEqual((cm.exception.status, cm.exception.code, cm.exception.license.expires_at),
157
+ (403, "license_expired", "2026-01-01T00:00:00.000Z"))
158
+
138
159
  def test_activate_missing_instance(self):
139
160
  with self.assertRaises(SendclapError) as cm:
140
161
  self.lic.activate("GOOD", "")
@@ -149,7 +170,7 @@ class SendclapTest(unittest.TestCase):
149
170
  r = self.lic.validate("GOOD", "other")
150
171
  self.assertEqual((r.valid, r.status, r.license.key), (False, "not_activated", "GOOD"))
151
172
  r = self.lic.validate("BAD", "dev-1")
152
- self.assertEqual((r.valid, r.status, r.license, r.product), (False, "invalid", None, None))
173
+ self.assertEqual((r.valid, r.status, r.license, r.product), (False, "not_found", None, None))
153
174
  r = self.lic.validate("REFUNDED", "dev-1")
154
175
  self.assertEqual((r.valid, r.status, r.license, r.product), (False, "disabled", None, None))
155
176
 
@@ -187,6 +208,8 @@ class SendclapTest(unittest.TestCase):
187
208
  self.assertEqual(headers["Authorization"], "Bearer sc_test")
188
209
  g = self.api.get_checkout("0xabc")
189
210
  self.assertEqual((g["status"], g["url"]), ("pending", "http://x/checkout/0xabc"))
211
+ self.assertIsNone(g["paid_at"])
212
+ self.assertEqual(self.api.get_checkout("0xpaid")["paid_at"], "2026-11-14T10:00:00.000Z")
190
213
 
191
214
  def test_payments_page(self):
192
215
  page = self.api.list_payments(status="paid", limit=2)
File without changes
File without changes