licentivo-sdk 0.10.0__tar.gz

licentivo_sdk-0.10.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 spf86 and Licentivo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

licentivo_sdk-0.10.0/NOTICE

@@ -0,0 +1,17 @@
+Licentivo client SDKs
+Copyright (c) 2026 spf86 and Licentivo contributors
+Project: https://github.com/spf86/licentivo-sdk
+
+The MIT license applies to the Licentivo client SDK code, examples and
+installation tools. The licensing server and administration application are
+separate software and are not included in this SDK distribution.
+
+Bundled third-party source retains its original license:
+- cJSON: see sdk/c/vendor/cJSON-LICENSE (or c/vendor/cJSON-LICENSE).
+- Monocypher and its Ed25519 extension: see
+  sdk/c/vendor/Monocypher-LICENCE.md (or c/vendor/Monocypher-LICENCE.md).
+Native packages include these files in the licenses directory.
+
+External dependencies such as libcurl, OpenSSL, cryptography, undici and
+BouncyCastle retain their own licenses. Their installation is handled by
+the corresponding package manager or the target system.

licentivo_sdk-0.10.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: licentivo-sdk
+Version: 0.10.0
+Summary: Licentivo software licensing client
+License: MIT License
+        
+        Copyright (c) 2026 spf86 and Licentivo contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/spf86/licentivo-sdk
+Project-URL: Documentation, https://www.licentivo.com/en/docs.html
+Project-URL: Issues, https://github.com/spf86/licentivo-sdk/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: cryptography<49,>=44.0.1
+Dynamic: license-file
+
+# Licentivo Python SDK
+
+Add software license activation and protected features to a Python application without implementing the licensing HTTP protocol yourself.
+
+## Features
+
+- Activates a customer license, derives device identity, stores a private device credential and restores it after restart.
+- Verifies signed grants with pinned public keys and checks license/feature status before running your business callback.
+- Schedules policy heartbeats, supports permitted offline grants and returns floating seats on close.
+- Handles metered-feature reservation, commit/cancel and recovery of pending confirmations using a stable job ID.
+- Provides explicit refresh/deactivation, offline activation file exchange and structured error details.
+
+Your application supplies the activation interface, business function and durable business results. The SDK handles the authorization workflow; management API keys stay on your server.
+
+## Installation
+
+Use Python 3.10+ and a virtual environment. Install the pinned release from PyPI:
+
+```bash
+python -m pip install "licentivo-sdk==0.10.0"
+```
+
+For an offline release, install local sources with `python -m pip install ./sdk/python`,
+or a downloaded wheel with `python -m pip install ./licentivo_sdk-0.10.0-py3-none-any.whl`.
+The [website installation guide](https://www.licentivo.com/en/docs.html#sdk) shows current release availability and the common installer.
+For the full starter, see QUICKSTART.md at the configured ZIP root and run `start.ps1` / `start.sh`.
+Keep `product.json` in application resources. Read the customer's key from your
+activation UI; after activation pass an empty string to restore the credential.
+
+```python
+from licentivo import Client
+from pathlib import Path
+
+with Client.open_with_license('product.json', customer_key, on_error=print) as client:
+    client.run_feature('export', lambda: Path('report.txt').write_text('Report\n'))
+    # In your app, keep this context open until the application exits.
+```
+
+For a configured metered feature, pass your business callback to the SDK:
+
+```python
+client.run_metered_feature('export', 1, persistent_job_id, export_report)
+```
+
+The SDK reserves, runs, confirms/cancels and stores a private journal. Retain your
+job ID and durable business result. Repeating this call after a pending commit,
+including after restart, retries only confirmation and never repeats business.
+If a process crashes during the callback, inspect its result and call
+`resolve_metered_feature(job_id, succeeded)`; the SDK does not guess or rerun it.
+One workflow runs per client; different processes need different job IDs.
+The lower-level reserve/commit/cancel methods remain available for custom flows.
+The counter requires an online connection. `consume()` immediately charges
+usage and is for operations that cannot subsequently fail.
+
+`offline_request()` returns a dictionary to save as JSON;
+`import_offline(request_dict, response_dict)` verifies an offline activation.
+Closing a floating client releases its seat; device bindings are kept.
+
+Accept an ordinary `lv_lic_...` key or a replacement computer's `lv_tmp_...`
+code through your activation UI. After activation, the SDK saves a machine-scoped
+credential beside `cache_path`. Later starts can use an empty `license_key`
+with the same product, trusted keys and cache path. Keep the credential in the
+user's application data directory; never ship it with the software.
+
+With a valid device-bound offline cache, startup restores access immediately
+and refreshes online in the background. Online-only and floating licenses wait
+for the server. `feature_status('export')` explains a denial without a network
+request. Call `close()` on exit. Python's synchronous HTTP transport may finish
+an in-flight request after close; its timeout bounds that work.
+
+Run `python desktop.py product.json` for an activation and report-export window.
+It retains an export journal for commit recovery. An interrupted output still
+requires your application to check whether the business operation completed.

licentivo_sdk-0.10.0/README.md

@@ -0,0 +1,73 @@
+# Licentivo Python SDK
+
+Add software license activation and protected features to a Python application without implementing the licensing HTTP protocol yourself.
+
+## Features
+
+- Activates a customer license, derives device identity, stores a private device credential and restores it after restart.
+- Verifies signed grants with pinned public keys and checks license/feature status before running your business callback.
+- Schedules policy heartbeats, supports permitted offline grants and returns floating seats on close.
+- Handles metered-feature reservation, commit/cancel and recovery of pending confirmations using a stable job ID.
+- Provides explicit refresh/deactivation, offline activation file exchange and structured error details.
+
+Your application supplies the activation interface, business function and durable business results. The SDK handles the authorization workflow; management API keys stay on your server.
+
+## Installation
+
+Use Python 3.10+ and a virtual environment. Install the pinned release from PyPI:
+
+```bash
+python -m pip install "licentivo-sdk==0.10.0"
+```
+
+For an offline release, install local sources with `python -m pip install ./sdk/python`,
+or a downloaded wheel with `python -m pip install ./licentivo_sdk-0.10.0-py3-none-any.whl`.
+The [website installation guide](https://www.licentivo.com/en/docs.html#sdk) shows current release availability and the common installer.
+For the full starter, see QUICKSTART.md at the configured ZIP root and run `start.ps1` / `start.sh`.
+Keep `product.json` in application resources. Read the customer's key from your
+activation UI; after activation pass an empty string to restore the credential.
+
+```python
+from licentivo import Client
+from pathlib import Path
+
+with Client.open_with_license('product.json', customer_key, on_error=print) as client:
+    client.run_feature('export', lambda: Path('report.txt').write_text('Report\n'))
+    # In your app, keep this context open until the application exits.
+```
+
+For a configured metered feature, pass your business callback to the SDK:
+
+```python
+client.run_metered_feature('export', 1, persistent_job_id, export_report)
+```
+
+The SDK reserves, runs, confirms/cancels and stores a private journal. Retain your
+job ID and durable business result. Repeating this call after a pending commit,
+including after restart, retries only confirmation and never repeats business.
+If a process crashes during the callback, inspect its result and call
+`resolve_metered_feature(job_id, succeeded)`; the SDK does not guess or rerun it.
+One workflow runs per client; different processes need different job IDs.
+The lower-level reserve/commit/cancel methods remain available for custom flows.
+The counter requires an online connection. `consume()` immediately charges
+usage and is for operations that cannot subsequently fail.
+
+`offline_request()` returns a dictionary to save as JSON;
+`import_offline(request_dict, response_dict)` verifies an offline activation.
+Closing a floating client releases its seat; device bindings are kept.
+
+Accept an ordinary `lv_lic_...` key or a replacement computer's `lv_tmp_...`
+code through your activation UI. After activation, the SDK saves a machine-scoped
+credential beside `cache_path`. Later starts can use an empty `license_key`
+with the same product, trusted keys and cache path. Keep the credential in the
+user's application data directory; never ship it with the software.
+
+With a valid device-bound offline cache, startup restores access immediately
+and refreshes online in the background. Online-only and floating licenses wait
+for the server. `feature_status('export')` explains a denial without a network
+request. Call `close()` on exit. Python's synchronous HTTP transport may finish
+an in-flight request after close; its timeout bounds that work.
+
+Run `python desktop.py product.json` for an activation and report-export window.
+It retains an export journal for commit recovery. An interrupted output still
+requires your application to check whether the business operation completed.

licentivo_sdk-0.10.0/licentivo.py

@@ -0,0 +1,430 @@
+"""Licentivo runtime SDK, Python 3.10+. Pin public keys; never put a vendor API key here."""
+import base64
+import hashlib
+import json
+import licentivo_tasks
+import os
+import platform
+import subprocess
+import random
+import re
+import tempfile
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from pathlib import Path
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+LIMIT = 16384
+FIELDS = {'version','key_id','tenant_id','product_id','license_id','device_id','activation_id','mode','features','max_devices','issued_at','expires_at'}
+UUID = re.compile(r'^[0-9a-fA-F]{8}(-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}$')
+
+def _pairs(pairs):
+    result = {}
+    for key,value in pairs:
+        if key in result: raise ValueError('duplicate JSON field')
+        result[key] = value
+    return result
+
+def loads(data):
+    if len(data) > LIMIT: raise ValueError('response size limit')
+    return json.loads(data, object_pairs_hook=_pairs, parse_constant=lambda x: (_ for _ in ()).throw(ValueError('invalid number')))
+
+def decode(s):
+    if not isinstance(s,str) or not re.fullmatch(r'[A-Za-z0-9_-]+',s): raise ValueError('invalid base64url')
+    b = base64.urlsafe_b64decode(s + '='*((-len(s))%4))
+    if base64.urlsafe_b64encode(b).decode().rstrip('=') != s: raise ValueError('noncanonical base64url')
+    return b
+
+def system_device_id(product):
+    system=platform.system(); identity=''
+    if system=='Windows':
+        import winreg
+        with winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE,r'SOFTWARE\Microsoft\Cryptography',0,winreg.KEY_READ|winreg.KEY_WOW64_64KEY) as key:
+            identity=winreg.QueryValueEx(key,'MachineGuid')[0]
+    elif system=='Linux':
+        for p in ['/etc/machine-id','/var/lib/dbus/machine-id']:
+            try: identity=Path(p).read_text().strip()
+            except OSError: continue
+            if identity: break
+    elif system=='Darwin':
+        result=subprocess.check_output(['/usr/sbin/ioreg','-rd1','-c','IOPlatformExpertDevice'],timeout=3,text=True)
+        match=re.search(r'"IOPlatformUUID"\s*=\s*"([0-9A-Fa-f-]+)"',result)
+        if match: identity=match[1]
+    identity=identity.strip().lower()
+    if not re.fullmatch(r'(?:[0-9a-f]{32}|[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12})',identity) or not identity.replace('-','').strip('0'):
+        raise ValueError('OS machine identity unavailable; cannot bind license')
+    return hashlib.sha256(('LicenovaDevice/v2\n'+product.lower()+'\n'+identity).encode()).hexdigest()
+
+def machine_profile(product):
+    system=system_device_id(product); hardware='';description='';os_name=platform.system()
+    try:
+        if os_name=='Windows':
+            result=subprocess.check_output(['powershell.exe','-NoProfile','-NonInteractive','-Command','(Get-CimInstance Win32_ComputerSystemProduct).UUID; $v=Get-CimInstance Win32_ComputerSystem; $v.Manufacturer; $v.Model'],timeout=5,text=True,creationflags=subprocess.CREATE_NO_WINDOW)
+            hardware=result.strip().splitlines()[0];description=result
+        elif os_name=='Linux':
+            try: hardware=Path('/sys/class/dmi/id/product_uuid').read_text()
+            except OSError: pass
+            for path in ['/sys/class/dmi/id/sys_vendor','/sys/class/dmi/id/product_name']:
+                try: description+=' '+Path(path).read_text()
+                except OSError: pass
+            if Path('/.dockerenv').exists(): description+=' virtual machine'
+        elif os_name=='Darwin':
+            result=subprocess.check_output(['/usr/sbin/ioreg','-rd1','-c','IOPlatformExpertDevice'],timeout=5,text=True)
+            hardware=re.search(r'"IOPlatformUUID"\s*=\s*"([0-9A-Fa-f-]+)"',result)[1];description=result
+    except (OSError,subprocess.SubprocessError,IndexError,TypeError): pass
+    hardware=hardware.strip().lower();hw=''
+    if UUID.fullmatch(hardware) and hardware.replace('-','').strip('0f'):
+        hw=hashlib.sha256(('LicenovaHardware/v1\n'+product.lower()+'\n'+hardware).encode()).hexdigest()
+    profile={'version':3,'system_id':system,'hardware_id':hw,'virtual_machine':bool(re.search(r'vmware|virtualbox|virtual machine|kvm|qemu|xen|parallels',description,re.I)),'platform':{'Windows':'windows','Linux':'linux','Darwin':'darwin'}[os_name]}
+    return profile,hashlib.sha256(('LicenovaDevice/v3\n'+product.lower()+'\n'+system+'\n'+hw).encode()).hexdigest()
+def machine_device_id(product): return machine_profile(product)[1]
+
+def extended_claims(c):
+    if 'offline_request_id' in c and (not isinstance(c['offline_request_id'],str) or not UUID.fullmatch(c['offline_request_id'])): raise ValueError('invalid offline request ID')
+    if 'capabilities' not in c: return
+    x=c['capabilities'];allowed={'license_model','session_id','session_expires_at','app_version','version_released_at','maintenance_until'}
+    if not isinstance(x,dict) or set(x)-allowed or x.get('license_model') not in ['node_locked','floating']: raise ValueError('invalid license capabilities')
+    for field in ['session_expires_at','version_released_at','maintenance_until']:
+        if field in x and (type(x[field]) is not int or not 0<=x[field]<=253402300799): raise ValueError('invalid entitlement date')
+    if 'app_version' in x and (not isinstance(x['app_version'],str) or not re.fullmatch(r'(0|[1-9][0-9]{0,8})\.(0|[1-9][0-9]{0,8})\.(0|[1-9][0-9]{0,8})',x['app_version'])): raise ValueError('invalid application version')
+    if x['license_model']=='floating' and (not isinstance(x.get('session_id'),str) or not UUID.fullmatch(x['session_id']) or x.get('session_expires_at',0)<=c['issued_at'] or c['expires_at']>x['session_expires_at'] or c.get('runtime_policy',{}).get('heartbeat_seconds',0)==0 or policy_mode(c)=='permanent'): raise ValueError('invalid floating session')
+    if x.get('version_released_at',0)>c['issued_at'] or x.get('maintenance_until',0)>0 and (not x.get('app_version') or x.get('version_released_at',0)==0 or x['version_released_at']>x['maintenance_until']): raise ValueError('invalid maintenance entitlement')
+
+def policy_mode(c): return c.get('runtime_policy',{}).get('offline_mode','limited')
+def max_span(c):
+    if 'runtime_policy' not in c: return 86400
+    p=c['runtime_policy']
+    if not isinstance(p,dict) or set(p)!={'offline_mode','heartbeat_seconds','offline_seconds'} or any(type(p[f]) is not int for f in ['heartbeat_seconds','offline_seconds']): raise ValueError('invalid runtime policy')
+    mode,h,o=p['offline_mode'],p['heartbeat_seconds'],p['offline_seconds']
+    if h!=0 and not 10<=h<=86400: raise ValueError('invalid heartbeat interval')
+    if mode=='permanent' and o==0: return 253402300799-c['issued_at']
+    if mode=='none' and o==0: return 10 if h==0 else h+(h+9)//10+30
+    if mode=='limited' and 1<=o<=31536000: return o
+    raise ValueError('invalid runtime policy')
+
+def verify(envelope, keys, product, device, now=None):
+    now = int(time.time()) if now is None else now
+    if set(envelope) != {'version','key_id','payload','signature'} or type(envelope['version']) is not int or envelope['version'] != 1: raise ValueError('invalid envelope')
+    raw = decode(keys[envelope['key_id']]); payload = decode(envelope['payload']); signature = decode(envelope['signature'])
+    if len(raw)!=32 or len(signature)!=64 or len(payload)>LIMIT: raise ValueError('invalid key/signature length')
+    Ed25519PublicKey.from_public_bytes(raw).verify(signature,b'LicenovaLease/v1\n'+payload)
+    c = loads(payload)
+    if set(c) != FIELDS | (set(c)&{'runtime_policy','capabilities','offline_request_id'}): raise ValueError('invalid claims fields')
+    if type(c['version']) is not int or c['version']!=1 or c['key_id']!=envelope['key_id'] or c['product_id']!=product or c['device_id']!=device: raise ValueError('lease context mismatch')
+    if any(not isinstance(c[f],str) or not UUID.fullmatch(c[f]) for f in ['tenant_id','product_id','license_id','activation_id']): raise ValueError('invalid identifiers')
+    if not re.fullmatch(r'[0-9a-f]{64}',device) or c['mode'] not in ['perpetual','timed','trial']: raise ValueError('invalid mode/device')
+    if any(type(c[f]) is not int for f in ['max_devices','issued_at','expires_at']): raise ValueError('invalid integer claim')
+    if not 1<=c['max_devices']<=10000 or c['issued_at']<=0 or not 0<c['expires_at']-c['issued_at']<=max_span(c) or c['expires_at']>253402300799 or c['issued_at']>now+300 or now>=c['expires_at']: raise ValueError('expired lease/clock')
+    fs=c['features']
+    if not isinstance(fs,list) or len(fs)>32 or any(not isinstance(f,str) or not re.fullmatch(r'[A-Za-z0-9_.-]{1,64}',f) for f in fs) or sorted(set(fs))!=fs: raise ValueError('invalid features')
+    extended_claims(c)
+    return c
+
+def device_id(product, installation_id):
+    return hashlib.sha256(('licentivo-device-v1\n'+product+'\n'+installation_id.strip().lower()).encode()).hexdigest()
+
+class APIError(Exception):
+    def __init__(self, status, code, request_id='', retry_after_seconds=0):
+        self.status=status; self.code=code; self.request_id=request_id; self.retryable=status==429 or status>=500; self.retry_after_seconds=retry_after_seconds; super().__init__(f'Licentivo {code} ({status})')
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self,*args,**kwargs): return None
+
+class Client:
+    def __init__(self, config):
+        self.feature_task_lock = threading.Lock()
+        self.config=dict(config); self.config.setdefault('license_key',''); self.config['base_url']=self.config['base_url'].rstrip('/');
+        if not self.config.get('cache_path'): self.config['cache_path']=str(Path(os.environ.get('LOCALAPPDATA') or os.environ.get('XDG_CACHE_HOME') or str(Path.home()/'.cache'))/'Licentivo'/hashlib.sha256((self.config['base_url']+'\n'+self.config['product_id']).encode()).hexdigest()/'lease.json')
+        self.profile,self.config['device_id']=machine_profile(config['product_id']); self.session_id=str(uuid.uuid4()); config=self.config; u=urllib.parse.urlsplit(config['base_url'])
+        if u.username or not u.hostname or u.query or u.fragment or u.path not in ['','/']: raise ValueError('base_url must be an origin')
+        if u.scheme!='https' and not (config.get('allow_http') is True and u.scheme=='http' and u.hostname in ['localhost','127.0.0.1','::1']): raise ValueError('HTTPS required')
+        if not re.fullmatch(r'[0-9a-f]{64}',config['device_id']) or config['license_key'] and not re.fullmatch(r'lv_(lic|tmp)_[A-Za-z0-9_-]{43}',config['license_key']): raise ValueError('invalid device/license')
+        if not config['trusted_keys'] or any(len(decode(k))!=32 for k in config['trusted_keys'].values()): raise ValueError('pin a public key')
+        self.lock=threading.RLock(); self.state=None; self.interval=3600; self.wall=0; self.tick=time.monotonic(); self.stop=threading.Event(); self.thread=None; self.refresh_thread=None; self.closed=False
+        self.timeout=config.get('timeout_seconds',10)
+        if not isinstance(self.timeout,(int,float)) or not 1<=self.timeout<=120: raise ValueError('timeout_seconds must be 1–120')
+        handlers=[_NoRedirect()]
+        if config.get('proxy_url'): handlers.append(urllib.request.ProxyHandler({'http':config['proxy_url'],'https':config['proxy_url']}))
+        self.opener=urllib.request.build_opener(*handlers);self.on_status_changed=None;self.last_error=None;self.online=False;self.retry_at=0;self.snapshot=(None,0,self.tick)
+        self.auth=None;self.auth_dirty=False;self._load_credential()
+        if not config['license_key'] and not self.auth: raise ValueError('enter a license key or temporary activation code')
+        try:
+            p=Path(config.get('cache_path','')); s=loads(p.read_bytes()) if p.is_file() and p.stat().st_size<=LIMIT else None
+            if s and s['version']==1 and s['license_hash']==self._hash() and time.time()+300>=s['observed_at']:
+                c=verify(s['lease'],config['trusted_keys'],config['product_id'],config['device_id'])
+                if policy_mode(c)!='none' and c.get('capabilities',{}).get('license_model')!='floating' and c.get('capabilities',{}).get('app_version','')==config.get('app_version',''):
+                    self.state=s;self.wall=s['observed_at'];self.interval=c.get('runtime_policy',{}).get('heartbeat_seconds',3600)
+        except Exception: pass  # A corrupt/expired cache never grants access.
+        self._publish(False)
+
+    def _hash(self): return self.auth['source_hash'] if not self.config['license_key'] and self.auth else hashlib.sha256(self.config['license_key'].encode()).hexdigest()
+    def _temporary(self): return bool(self.config['license_key']) or self.auth is not None
+    def _runtime_key(self): return self.auth.get('device_key') or self.config['license_key'] if self.auth else self.config['license_key']
+    def _load_credential(self):
+        if not self.config.get('cache_path'): return
+        try:
+            path=Path(self.config['cache_path']+'.credential.json')
+            if path.stat().st_size>LIMIT: return
+            s=loads(path.read_bytes())
+            if s.get('version')!=1 or s.get('origin')!=self.config['base_url'] or not re.fullmatch(r'[0-9a-f]{64}',s.get('source_hash','')) or self.config['license_key'] and s.get('source_hash')!=self._hash() or any(s.get(k)!=self.config[k] for k in ['product_id','device_id']) or not UUID.fullmatch(s.get('request_id','')) or not UUID.fullmatch(s.get('session_id','')) or s.get('device_key') and not re.fullmatch(r'lv_dev_[A-Za-z0-9_-]{43}',s['device_key']): return
+            if not self.config['license_key'] and not s.get('device_key'): return
+            self.auth=s
+            if not s.get('device_key'): self.session_id=s['session_id']
+        except (OSError,ValueError,KeyError,TypeError): pass
+    def _prepare_credential(self):
+        if not self._temporary(): return
+        if not self.config.get('cache_path'): raise ValueError('cache_path required to retain a transferred license')
+        if not self.auth:
+            self.auth={'version':1,'origin':self.config['base_url'],'source_hash':self._hash(),'product_id':self.config['product_id'],'device_id':self.config['device_id'],'device_key':'','request_id':str(uuid.uuid4()),'session_id':self.session_id}
+            self.auth_dirty=True
+        if self.auth_dirty: self._save_credential()
+    def _save_credential(self):
+        p=Path(self.config['cache_path']+'.credential.json');p.parent.mkdir(parents=True,exist_ok=True)
+        fd,tmp=tempfile.mkstemp(prefix='.credential-',dir=p.parent)
+        try:
+            os.chmod(tmp,0o600)
+            with os.fdopen(fd,'w',encoding='utf-8') as f: json.dump(self.auth,f,separators=(',',':'))
+            os.replace(tmp,p);self.auth_dirty=False
+        finally:
+            if os.path.exists(tmp): os.unlink(tmp)
+    def _accept_credential(self,result):
+        if not self._temporary() or self.auth and self.auth.get('device_key'): return
+        if not re.fullmatch(r'lv_dev_[A-Za-z0-9_-]{43}',result.get('device_key','')):
+            if not self.config['license_key'].startswith('lv_tmp_'): return
+            raise ValueError('server omitted device credential')
+        self._prepare_credential();self.auth['device_key']=result['device_key'];self.auth_dirty=True;self._save_credential()
+    def _check(self):
+        if self.wall and time.time() < self.wall+(time.monotonic()-self.tick)-300: raise ValueError('clock rollback; verify online')
+        if not self.state: raise ValueError('no valid lease')
+        c=verify(self.state['lease'],self.config['trusted_keys'],self.config['product_id'],self.config['device_id']);self._context(c);return c
+    def _invalidate(self):
+        self.state=None
+        self._publish(False)
+        path=self.config.get('cache_path')
+        if path:
+            try: Path(path).unlink(missing_ok=True)
+            except OSError: pass
+    def _save(self):
+        path=self.config.get('cache_path')
+        if not path: return
+        p=Path(path);p.parent.mkdir(parents=True,exist_ok=True)
+        fd,tmp=tempfile.mkstemp(prefix='.lease-',dir=p.parent)
+        try:
+            os.chmod(tmp,0o600)
+            with os.fdopen(fd,'w',encoding='utf-8') as f: json.dump(self.state,f,separators=(',',':'))
+            os.replace(tmp,p)
+        finally:
+            if os.path.exists(tmp): os.unlink(tmp)
+    def _request(self,operation,activation,operation_id=None,extra=None):
+        self._prepare_credential()
+        cfg=self.config; body=json.dumps(self._body(activation) | (extra or {})).encode()
+        idem=operation_id or str(uuid.uuid4());last=None
+        if operation=='activate' and self._temporary() and not self.auth.get('device_key') and not self.state: idem=self.auth['request_id']
+        for attempt in range(2):
+            if attempt: time.sleep(.2)
+            req=urllib.request.Request(cfg['base_url'].rstrip('/')+'/api/v1/'+operation,body,{'Content-Type':'application/json','Idempotency-Key':idem},method='POST')
+            try:
+                try: res=self.opener.open(req,timeout=self.timeout)
+                except urllib.error.HTTPError as e: res=e
+                with res:
+                    status=res.code; request_headers=res.headers; b=res.read(LIMIT+1)
+                if len(b)>LIMIT: raise ValueError('oversized response')
+                try: env=loads(b)
+                except ValueError:
+                    if status!=429 and status<500: raise
+                    retry=request_headers.get('Retry-After','0')
+                    error=APIError(status,'UNEXPECTED_RESPONSE',request_headers.get('X-Request-ID',''),min(86400,int(retry)) if retry.isdigit() else 0)
+                    if status>=500: last=error;continue
+                    raise error
+                if status!=200 or env.get('error'):
+                    retry=int(request_headers.get('Retry-After','0')) if request_headers.get('Retry-After','0').isdigit() else 0
+                    error=APIError(status,env.get('error',{}).get('code','UNEXPECTED_RESPONSE'),env.get('request_id',''),min(86400,retry))
+                    if status>=500: last=error;continue
+                    raise error
+                return env['data']
+            except (urllib.error.URLError,TimeoutError,OSError) as e: last=e
+        raise last
+    def _call(self,operation,force_online=False):
+        with self.lock:
+            try:
+                cached=self._check()
+                if not force_online and operation=='activate' and policy_mode(cached)=='permanent' and cached['runtime_policy']['heartbeat_seconds']==0: return cached
+            except Exception: pass
+            activation=''
+            if operation!='activate':
+                if not self.state: raise ValueError('activate first')
+                activation=loads(decode(self.state['lease']['payload']))['activation_id']
+            try: result=self._request(operation,activation)
+            except Exception as e:
+                transient=isinstance(e,(urllib.error.URLError,TimeoutError,OSError)) or isinstance(e,APIError) and e.retryable
+                if transient:
+                    try:
+                        c=self._check()
+                        if not force_online and policy_mode(c)!='none': self._publish(False,e);return c
+                        if policy_mode(c)=='none': self._invalidate()
+                    except Exception: pass
+                    self._publish(False,e);raise e
+                self._invalidate();self._publish(False,e);raise
+            try:
+                c=verify(result['lease'],self.config['trusted_keys'],self.config['product_id'],self.config['device_id'])
+                self._context(c)
+                if c['activation_id']!=result['activation_id']: raise ValueError('activation mismatch')
+            except Exception: self._invalidate();raise
+            self._accept_credential(result)
+            self.wall=time.time();self.tick=time.monotonic();self.state={'version':1,'license_hash':self._hash(),'lease':result['lease'],'observed_at':int(self.wall)}
+            self.interval=c.get('runtime_policy',{}).get('heartbeat_seconds',max(10,min(86400,result.get('heartbeat_seconds',3600))));self._save();self._publish(True);return c
+    def activate(self): return self._call('activate')
+    def validate(self): return self._call('validate')
+    def heartbeat(self): return self._call('heartbeat')
+    def refresh_online(self): return self._call('activate',True)
+    def check_feature(self,name):
+        return self.feature_status(name)['allowed']
+    def deactivate(self):
+        with self.lock:
+            claims=loads(decode(self.state['lease']['payload'])) if self.state else {}
+            activation=claims.get('activation_id','');floating=claims.get('capabilities',{}).get('license_model')=='floating'
+            self._invalidate()
+            if activation: self._request('deactivate',activation)
+            if not floating: Path(self.config['cache_path']+'.credential.json').unlink(missing_ok=True);self.auth=None
+            self._publish(False,APIError(0,'DEVICE_RELEASED'))
+    def start_heartbeat(self,on_error=None):
+        try:
+            if self.interval==0: return
+        except Exception: pass
+        if self.thread and self.thread.is_alive(): return
+        self.stop.clear()
+        def run():
+            while self.interval and not self.stop.wait(max(max(600,self.interval)*random.uniform(1,1.1),self.retry_at-time.time())):
+                try: self.heartbeat()
+                except Exception as e:
+                    if on_error: on_error(e)
+        self.thread=threading.Thread(target=run,daemon=True);self.thread.start()
+    def close(self):
+        if self.closed: return
+        self.closed=True
+        self.stop.set()
+        for worker in [self.thread,self.refresh_thread]:
+            if worker and worker is not threading.current_thread(): worker.join(timeout=5)
+        self.thread=None
+        self.refresh_thread=None
+        try:
+            if self._check().get('capabilities',{}).get('license_model')=='floating': self.deactivate()
+        except Exception: pass
+    def _context(self,c):
+        x=c.get('capabilities')
+        if x and (x.get('app_version','')!=self.config.get('app_version','') or x['license_model']=='floating' and x.get('session_id')!=self.session_id): raise ValueError('lease belongs to another version/session')
+    def _body(self,activation=''):
+        return {k:self.config.get(k,'') for k in ['product_id','device_id','device_name','app_version']} | {'license_key':self._runtime_key(),'activation_id':activation,'session_id':self.session_id,'device_profile':self.profile}
+    def start(self,on_error=None):
+        if self.closed: raise RuntimeError('client is closed')
+        try:
+            result=self._check()
+            if policy_mode(result)=='none' or result.get('capabilities',{}).get('license_model')=='floating': raise ValueError('online startup required')
+        except Exception:
+            result=self.activate();self.start_heartbeat(on_error);return result
+        self.start_heartbeat(on_error)
+        def refresh():
+            if self.stop.is_set(): return
+            try: self.refresh_online()
+            except Exception as e:
+                if on_error and not self.stop.is_set(): on_error(e)
+        if not self.refresh_thread or not self.refresh_thread.is_alive():
+            self.refresh_thread=threading.Thread(target=refresh,daemon=True);self.refresh_thread.start()
+        return result
+    @classmethod
+    def open(cls,path,on_error=None):
+        client=cls(loads(Path(path).read_bytes()))
+        try: client.start(on_error);return client
+        except Exception: client.close();raise
+    @classmethod
+    def open_with_license(cls,path,license_key,on_error=None):
+        """Load shared product settings and use the customer's license key."""
+        config=loads(Path(path).read_bytes())
+        config['license_key']=license_key.strip()
+        client=cls(config)
+        try: client.start(on_error);return client
+        except Exception: client.close();raise
+    def consume(self,feature,quantity,operation_id):
+        if not operation_id: raise ValueError('retain an operation_id for retries')
+        with self.lock:
+            activation=self._check()['activation_id']
+            try: return self._request('consume',activation,operation_id,{'feature':feature,'quantity':quantity})['consumption']
+            except APIError as e:
+                if e.code in ['LICENSE_REVOKED','LICENSE_SUSPENDED','LICENSE_EXPIRED','DEVICE_RELEASED','DEVICE_CREDENTIAL_REVOKED']: self._invalidate()
+                self._publish(False,e)
+                raise
+    def offline_request(self,operation='activate'):
+        with self.lock:
+            self._prepare_credential()
+            if operation not in ['activate','deactivate']: raise ValueError('invalid offline operation')
+            activation=''
+            if operation=='deactivate': activation=self._check()['activation_id'];self._invalidate()
+            return self._body(activation) | {'version':1,'request_id':str(uuid.uuid4()),'created_at':int(time.time()),'operation':operation}
+    def import_offline(self,request,response):
+        with self.lock:
+            if response.get('version')!=1 or request.get('operation')!='activate' or response.get('operation')!='activate' or response.get('request_id')!=request.get('request_id') or any(request.get(k)!=self._body().get(k) for k in ['product_id','device_id','license_key']): raise ValueError('offline context mismatch')
+            result=response['result'];c=verify(result['lease'],self.config['trusted_keys'],self.config['product_id'],self.config['device_id']);self._context(c)
+            if policy_mode(c)=='none' or c.get('offline_request_id')!=request['request_id'] or c['activation_id']!=result['activation_id']: raise ValueError('offline signature context mismatch')
+            self._accept_credential(result)
+            self.wall=time.time();self.tick=time.monotonic();self.state={'version':1,'license_hash':self._hash(),'lease':result['lease'],'observed_at':int(self.wall)};self.interval=c['runtime_policy']['heartbeat_seconds'];self._save();self._publish(False);return c
+    def _publish(self,online,error=None):
+        before=self.status();self.snapshot=(self.state,self.wall,self.tick);self.online=online;self.last_error=error
+        if isinstance(error,APIError) and error.retry_after_seconds: self.retry_at=time.time()+error.retry_after_seconds
+        after=self.status()
+        if before!=after and self.on_status_changed:
+            callback=self.on_status_changed
+            threading.Thread(target=lambda:callback(after),daemon=True).start()
+    def status(self):
+        state,wall,tick=self.snapshot
+        result={'state':'verification_required','allowed':False,'code':'','request_id':'','retryable':False,'lease_valid_until':0}
+        if self.last_error:
+            result.update(code=getattr(self.last_error,'code','NETWORK_UNAVAILABLE'),request_id=getattr(self.last_error,'request_id',''),retryable=getattr(self.last_error,'retryable',True))
+        try:
+            if wall and time.time()<wall+time.monotonic()-tick-300: raise ValueError('clock rollback')
+            claims=verify(state['lease'],self.config['trusted_keys'],self.config['product_id'],self.config['device_id']);self._context(claims)
+            result.update(state='active' if self.online else 'offline_valid',allowed=True,lease_valid_until=claims['expires_at'])
+        except Exception: pass
+        result['state']={'LICENSE_EXPIRED':'expired','LICENSE_REVOKED':'revoked','LICENSE_SUSPENDED':'revoked','DEVICE_RELEASED':'released','DEVICE_CREDENTIAL_REVOKED':'released','FEATURE_QUOTA_EXCEEDED':'quota_exhausted'}.get(result['code'],result['state'])
+        return result
+    def run_feature(self, name, action):
+        """Run a non-metered business action only when the signed grant allows it."""
+        if not callable(action): raise TypeError('business action is required')
+        status = self.feature_status(name)
+        if not status['allowed']:
+            raise RuntimeError(f"feature denied: {status['code']} ({status['state']}); request_id={status['request_id']}")
+        return action()
+
+    def run_metered_feature(self, name, quantity, operation_id, action):
+        return licentivo_tasks.run(self, name, quantity, operation_id, action)
+
+    def resolve_metered_feature(self, operation_id, succeeded):
+        return licentivo_tasks.resolve(self, operation_id, succeeded)
+
+    def feature_status(self,name):
+        result=self.status()
+        if result['allowed']:
+            try:
+                claims=verify(self.snapshot[0]['lease'],self.config['trusted_keys'],self.config['product_id'],self.config['device_id'])
+                if name not in claims['features']: result.update(allowed=False,code='FEATURE_NOT_ENTITLED')
+            except Exception: result.update(allowed=False,state='verification_required')
+        return result
+    def _reservation(self,operation,operation_id,extra):
+        if not operation_id: raise ValueError('retain operation_id for retries')
+        with self.lock:
+            activation=self._check()['activation_id']
+            try:
+                result=self._request('consume/'+operation,activation,operation_id,extra)['reservation'];self._publish(True);return result
+            except Exception as e:
+                if getattr(e,'code','') in ['LICENSE_REVOKED','LICENSE_SUSPENDED','LICENSE_EXPIRED','DEVICE_RELEASED','DEVICE_CREDENTIAL_REVOKED']: self._invalidate()
+                self._publish(False,e);raise
+    def reserve(self,feature,quantity,operation_id): return self._reservation('reserve',operation_id,{'feature':feature,'quantity':quantity})
+    def commit(self,reservation_id,operation_id): return self._reservation('commit',operation_id,{'reservation_id':reservation_id})
+    def cancel(self,reservation_id,operation_id): return self._reservation('cancel',operation_id,{'reservation_id':reservation_id})
+    def stop_client(self):
+        self.close()
+    def __enter__(self): return self
+    def __exit__(self,*args): self.close()

licentivo_sdk-0.10.0/licentivo_sdk.egg-info/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: licentivo-sdk
+Version: 0.10.0
+Summary: Licentivo software licensing client
+License: MIT License
+        
+        Copyright (c) 2026 spf86 and Licentivo contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/spf86/licentivo-sdk
+Project-URL: Documentation, https://www.licentivo.com/en/docs.html
+Project-URL: Issues, https://github.com/spf86/licentivo-sdk/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: cryptography<49,>=44.0.1
+Dynamic: license-file
+
+# Licentivo Python SDK
+
+Add software license activation and protected features to a Python application without implementing the licensing HTTP protocol yourself.
+
+## Features
+
+- Activates a customer license, derives device identity, stores a private device credential and restores it after restart.
+- Verifies signed grants with pinned public keys and checks license/feature status before running your business callback.
+- Schedules policy heartbeats, supports permitted offline grants and returns floating seats on close.
+- Handles metered-feature reservation, commit/cancel and recovery of pending confirmations using a stable job ID.
+- Provides explicit refresh/deactivation, offline activation file exchange and structured error details.
+
+Your application supplies the activation interface, business function and durable business results. The SDK handles the authorization workflow; management API keys stay on your server.
+
+## Installation
+
+Use Python 3.10+ and a virtual environment. Install the pinned release from PyPI:
+
+```bash
+python -m pip install "licentivo-sdk==0.10.0"
+```
+
+For an offline release, install local sources with `python -m pip install ./sdk/python`,
+or a downloaded wheel with `python -m pip install ./licentivo_sdk-0.10.0-py3-none-any.whl`.
+The [website installation guide](https://www.licentivo.com/en/docs.html#sdk) shows current release availability and the common installer.
+For the full starter, see QUICKSTART.md at the configured ZIP root and run `start.ps1` / `start.sh`.
+Keep `product.json` in application resources. Read the customer's key from your
+activation UI; after activation pass an empty string to restore the credential.
+
+```python
+from licentivo import Client
+from pathlib import Path
+
+with Client.open_with_license('product.json', customer_key, on_error=print) as client:
+    client.run_feature('export', lambda: Path('report.txt').write_text('Report\n'))
+    # In your app, keep this context open until the application exits.
+```
+
+For a configured metered feature, pass your business callback to the SDK:
+
+```python
+client.run_metered_feature('export', 1, persistent_job_id, export_report)
+```
+
+The SDK reserves, runs, confirms/cancels and stores a private journal. Retain your
+job ID and durable business result. Repeating this call after a pending commit,
+including after restart, retries only confirmation and never repeats business.
+If a process crashes during the callback, inspect its result and call
+`resolve_metered_feature(job_id, succeeded)`; the SDK does not guess or rerun it.
+One workflow runs per client; different processes need different job IDs.
+The lower-level reserve/commit/cancel methods remain available for custom flows.
+The counter requires an online connection. `consume()` immediately charges
+usage and is for operations that cannot subsequently fail.
+
+`offline_request()` returns a dictionary to save as JSON;
+`import_offline(request_dict, response_dict)` verifies an offline activation.
+Closing a floating client releases its seat; device bindings are kept.
+
+Accept an ordinary `lv_lic_...` key or a replacement computer's `lv_tmp_...`
+code through your activation UI. After activation, the SDK saves a machine-scoped
+credential beside `cache_path`. Later starts can use an empty `license_key`
+with the same product, trusted keys and cache path. Keep the credential in the
+user's application data directory; never ship it with the software.
+
+With a valid device-bound offline cache, startup restores access immediately
+and refreshes online in the background. Online-only and floating licenses wait
+for the server. `feature_status('export')` explains a denial without a network
+request. Call `close()` on exit. Python's synchronous HTTP transport may finish
+an in-flight request after close; its timeout bounds that work.
+
+Run `python desktop.py product.json` for an activation and report-export window.
+It retains an export journal for commit recovery. An interrupted output still
+requires your application to check whether the business operation completed.

licentivo_sdk-0.10.0/licentivo_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+NOTICE
+README.md
+licentivo.py
+licentivo_tasks.py
+pyproject.toml
+licentivo_sdk.egg-info/PKG-INFO
+licentivo_sdk.egg-info/SOURCES.txt
+licentivo_sdk.egg-info/dependency_links.txt
+licentivo_sdk.egg-info/requires.txt
+licentivo_sdk.egg-info/top_level.txt

licentivo_sdk-0.10.0/licentivo_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

licentivo_sdk-0.10.0/licentivo_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+cryptography<49,>=44.0.1

licentivo_sdk-0.10.0/licentivo_sdk.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+licentivo
+licentivo_tasks

licentivo_sdk-0.10.0/licentivo_tasks.py

@@ -0,0 +1,110 @@
+"""Private task journal. It contains IDs/outcome only, never customer business data."""
+import hashlib
+import json
+import os
+import tempfile
+from pathlib import Path
+
+
+def _path(client, operation_id):
+    if not isinstance(operation_id, str) or not 1 <= len(operation_id) <= 80 or any(ord(char) < 33 or ord(char) > 126 for char in operation_id):
+        raise ValueError('a stable operation_id of 1-80 non-whitespace ASCII characters is required')
+    digest = hashlib.sha256((client._hash() + '\n' + operation_id).encode()).hexdigest()
+    return Path(client.config['cache_path'] + '.task-' + digest + '.json')
+
+
+def _read(path, operation_id):
+    if not path.exists():
+        return dict(version=1, operation_id=operation_id, reservation_id='', state='')
+    raw = path.read_bytes()
+    task = json.loads(raw) if len(raw) <= 4096 else None
+    if not isinstance(task, dict) or task.get('version') != 1 or task.get('operation_id') != operation_id or not isinstance(task.get('feature'), str) or not task['feature'] or not isinstance(task.get('quantity'), int) or task['quantity'] <= 0 or not isinstance(task.get('state'), str) or not isinstance(task.get('reservation_id'), str) or not task['reservation_id']:
+        raise ValueError('invalid feature task journal; do not repeat business')
+    return task
+
+
+def _save(path, task):
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    fd, temporary = tempfile.mkstemp(prefix='.feature-task-', dir=path.parent)
+    try:
+        with os.fdopen(fd, 'w', encoding='utf-8') as stream:
+            json.dump(task, stream)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path)
+    finally:
+        Path(temporary).unlink(missing_ok=True)
+
+
+def _finish(client, path, task, succeeded):
+    try:
+        result = (client.commit if succeeded else client.cancel)(task['reservation_id'], task['operation_id'])
+    except Exception as error:
+        raise RuntimeError(f"confirmation pending for operation {task['operation_id']}; do not repeat business") from error
+    expected = 'committed' if succeeded else 'canceled'
+    if result['status'] != expected:
+        raise RuntimeError('reservation closed without the requested outcome; do not repeat business')
+    task['state'] = expected
+    _save(path, task)
+
+
+def run(client, feature, quantity, operation_id, action):
+    if not callable(action) or not isinstance(quantity, int) or isinstance(quantity, bool) or quantity <= 0:
+        raise ValueError('business action and positive integer quantity are required')
+    if not client.feature_task_lock.acquire(blocking=False):
+        raise RuntimeError('another feature task is running')
+    try:
+        path = _path(client, operation_id)
+        task = _read(path, operation_id)
+        state = task['state']
+        if state and (task['feature'] != feature or task['quantity'] != quantity):
+            raise ValueError('operation ID was already used for another feature or quantity')
+        task.update(feature=feature, quantity=quantity)
+        if state == 'committed': return
+        if state == 'commit_pending': return _finish(client, path, task, True)
+        if state == 'cancel_pending': _finish(client, path, task, False); state = 'canceled'
+        if state == 'canceled': raise RuntimeError('operation canceled; use a new job ID for a new action')
+        if state == 'business_running': raise RuntimeError('business outcome unknown; verify its result and call resolve_metered_feature')
+        if state: raise ValueError('invalid feature task state')
+        client.run_feature(feature, lambda: None)
+        hold = client.reserve(feature, quantity, operation_id)
+        if hold['status'] == 'committed':
+            task.update(reservation_id=hold['reservation_id'], state='committed')
+            _save(path, task)
+            return
+        if hold['status'] != 'pending': raise RuntimeError('reservation is closed; business was not run')
+        task.update(reservation_id=hold['reservation_id'], state='business_running')
+        try: _save(path, task)
+        except Exception:
+            try: client.cancel(hold['reservation_id'], operation_id)
+            except Exception: pass
+            raise
+        try: action()
+        except Exception:
+            task['state'] = 'cancel_pending'
+            try: _save(path, task); _finish(client, path, task, False)
+            except Exception: pass  # The original business error remains authoritative.
+            raise
+        task['state'] = 'commit_pending'
+        try: _save(path, task)
+        except Exception as error:
+            raise RuntimeError(f'business completed; journal update failed; do not repeat operation {operation_id}') from error
+        _finish(client, path, task, True)
+    finally:
+        client.feature_task_lock.release()
+
+
+def resolve(client, operation_id, succeeded):
+    if not client.feature_task_lock.acquire(blocking=False): raise RuntimeError('another feature task is running')
+    try:
+        path = _path(client, operation_id)
+        task = _read(path, operation_id)
+        state = task['state']
+        if state == ('committed' if succeeded else 'canceled'): return
+        if not isinstance(succeeded, bool) or not task['reservation_id'] or state not in ('business_running', 'commit_pending', 'cancel_pending') or state == 'commit_pending' and not succeeded or state == 'cancel_pending' and succeeded:
+            raise RuntimeError('task cannot be resolved with that outcome')
+        task['state'] = 'commit_pending' if succeeded else 'cancel_pending'
+        _save(path, task)
+        _finish(client, path, task, succeeded)
+    finally:
+        client.feature_task_lock.release()

licentivo_sdk-0.10.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "licentivo-sdk"
+version = "0.10.0"
+description = "Licentivo software licensing client"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {file = "LICENSE"}
+dependencies = ["cryptography>=44.0.1,<49"]
+
+[project.urls]
+Homepage = "https://github.com/spf86/licentivo-sdk"
+Documentation = "https://www.licentivo.com/en/docs.html"
+Issues = "https://github.com/spf86/licentivo-sdk/issues"
+
+[tool.setuptools]
+py-modules = ["licentivo", "licentivo_tasks"]
+license-files = ["LICENSE", "NOTICE"]

licentivo_sdk-0.10.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+