@corelicense/node 0.5.1 → 0.5.8

package/docs/api-reference.md

@@ -180,6 +180,8 @@ Mọi `LicenseError` có `code`, `source`, `message`, `toClientPayload()`, `toJS
 | `LICENSE_SUSPENDED` | 403 |
 | `LICENSE_EXPIRED` | 403 |
 | `LICENSE_INVALID` | 403 |
+| `LICENSE_NOT_FOUND` | 403 |
+| `LICENSE_NOT_STARTED` | 403 |
 | `OFFLINE_GRACE_EXPIRED` | 403 |
 | `FEATURE_DISABLED` | 403 |
 | `MODULE_NOT_LICENSED` | 403 |
@@ -187,6 +189,11 @@ Mọi `LicenseError` có `code`, `source`, `message`, `toClientPayload()`, `toJS
 | `MAX_INSTANCES` | 403 |
 | `INSTANCE_BLOCKED` | 403 |
 | `CONFIG_MISSING_ENV` | — (boot fail) |
+| `PRODUCT_NOT_FOUND` | — (boot fail) |
+| `PUBLIC_KEYS_NOT_PUBLISHED` | — (boot fail) |
+| `PUBLIC_KEYS_FETCH_FAILED` | — (boot fail) |
+| `LICENSE_API_UNREACHABLE` | — (boot fail) |
+| `LICENSE_API_TIMEOUT` | — (boot fail) |
 | `POLICY_SIGNATURE_ERROR` | — (boot fail) |
 | `BOOT_NOT_CALLED` | — |
 | `WORKER_NOT_ALLOWED` | — |
@@ -194,6 +201,50 @@ Mọi `LicenseError` có `code`, `source`, `message`, `toClientPayload()`, `toJS
 
 Danh sách đầy đủ trong source: `src/errors/codes.ts`
 
+`formatLicenseError(error)` trả thêm `retryable` và `httpStatus` (khi có) cho lỗi transport/API.
+
+### Ánh xạ response License Server → SDK
+
+**Client API** (`POST /v1/client/*`) — HTTP 200, body `ok: false`:
+
+| Server `code` | SDK `code` | Retry? |
+|---------------|------------|--------|
+| `LICENSE_REVOKED` | `LICENSE_REVOKED` | No |
+| `LICENSE_SUSPENDED` | `LICENSE_SUSPENDED` | No |
+| `LICENSE_EXPIRED` | `LICENSE_EXPIRED` | No |
+| `LICENSE_NOT_STARTED` | `LICENSE_NOT_STARTED` | No |
+| `INVALID_PRODUCT` | `PRODUCT_NOT_FOUND` | No |
+| `PRODUCT_NOT_FOUND` | `PRODUCT_NOT_FOUND` | No |
+| `INVALID_LICENSE` | `LICENSE_INVALID` | No |
+| `LICENSE_NOT_FOUND` | `LICENSE_NOT_FOUND` | No |
+| `LICENSE_INVALID` | `LICENSE_INVALID` | No |
+| `INSTANCE_BLOCKED` | `INSTANCE_BLOCKED` | No |
+| `MAX_INSTANCES` | `MAX_INSTANCES` | No |
+| `POLICY_SIGN_FAILED` | `POLICY_SIGNATURE_ERROR` | No |
+
+**Public keys** (`GET /v1/public/products/{id}/keys`) — HTTP lỗi, body `{ code, message }`:
+
+| Server `code` / HTTP | SDK `code` | Retry? |
+|----------------------|------------|--------|
+| `PRODUCT_NOT_FOUND` / 404 | `PRODUCT_NOT_FOUND` | No |
+| `PUBLIC_KEYS_NOT_PUBLISHED` / 404 | `PUBLIC_KEYS_NOT_PUBLISHED` | No |
+| `NOT_FOUND` / 404 (legacy) | `PUBLIC_KEYS_NOT_PUBLISHED` | No |
+| `RATE_LIMITED` / 429 | `RATE_LIMITED` | Yes |
+| 5xx / 408 | `PUBLIC_KEYS_FETCH_FAILED` | Yes |
+| 4xx khác | `PUBLIC_KEYS_FETCH_FAILED` | No |
+| Network / DNS / refused | `LICENSE_API_UNREACHABLE` | Yes |
+| Timeout | `LICENSE_API_TIMEOUT` | Yes |
+
+**License API HTTP lỗi** (400, 502, …) — không phải body `ok: false`:
+
+| Trường hợp | SDK `code` | Retry? |
+|------------|------------|--------|
+| 429 | `RATE_LIMITED` | Yes |
+| 5xx / 408 | `LICENSE_API_ERROR` | Yes |
+| 4xx khác | `LICENSE_API_ERROR` | No |
+| Network / DNS / refused | `LICENSE_API_UNREACHABLE` | Yes |
+| Timeout | `LICENSE_API_TIMEOUT` | Yes |
+
 ---
 
 ## Client API (License Server)

package/docs/installation.md

@@ -33,12 +33,14 @@ SDK không bắt buộc peer deps — tree-shake an toàn nếu chỉ dùng `Cor
 | `CORELICENSE_KEY` | License key do admin cấp (`CL-...` hoặc `CL1.<base64url-api>.CL-...`) |
 | `CORELICENSE_PRODUCT_ID` | Product ID trên License Server |
 
-### Tùy chọn
+### Tùy chọn (SDK tự xử lý nếu không set)
 
 | Biến | Mô tả | Mặc định |
 |------|--------|----------|
-| `CORELICENSE_API_URL` | Override URL License API | `https://api.corelicense.net` |
-| `CORELICENSE_PUBLIC_KEY` | Pin public key (SPKI PEM) — bỏ qua fetch keys | auto-fetch |
+| `CORELICENSE_API_URL` | Override URL License API | Từ key `CL1.*` hoặc `api.corelicense.net` |
+| `CORELICENSE_PUBLIC_KEY` | Pin public key (SPKI PEM) | Auto-fetch từ server |
+| `CORELICENSE_CACHE_PATH` | Thư mục cache | `~/.cache/corelicense/<scope>` |
+| `APP_DOMAIN` | Domain deploy (instance ID) | `os.hostname()` hoặc URL từ PaaS env |
 
 **Thứ tự resolve API URL** (không cần set thủ công trên production):
 
@@ -72,23 +74,18 @@ Server Go production cần `SDK_PUBLIC_URL=https://api.corelicense.net` khi gene
 ```ts
 import { CoreLicense, loadOptionsFromEnv } from '@corelicense/node';
 
-const license = new CoreLicense(
-  loadOptionsFromEnv({
-    cachePath: './storage/corelicense',
-    instance: {
-      strategy: 'install-id-domain-hash',
-      domain: process.env.APP_DOMAIN, // ví dụ: app.example.com
-    },
-    audit: {
-      enabled: true,
-      path: './storage/logs/corelicense.log',
-    },
-  }),
-);
-
+const license = new CoreLicense(loadOptionsFromEnv());
 await license.boot();
 ```
 
+Chỉ cần `CORELICENSE_KEY` + `CORELICENSE_PRODUCT_ID` trong `.env`. SDK tự quyết định:
+
+- API URL (từ license key)
+- Public keys (fetch + cache)
+- Cache path ổn định (`~/.cache/corelicense/...`)
+- Instance ID (lưu `install.id` + `instance.json` sau boot thành công)
+- Domain/instance fingerprint (`hostname` hoặc `APP_DOMAIN` nếu có)
+
 `loadOptionsFromEnv()` throw `ConfigError` (`CONFIG_MISSING_ENV`) nếu thiếu biến bắt buộc.
 
 ---

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@corelicense/node",
-  "version": "0.5.1",
+  "version": "0.5.8",
   "description": "CoreLicense Node.js SDK — runtime license and policy layer",
   "type": "module",
-  "homepage": "https://corelicense.net/docs/nodejs-sdk/intro",
+  "homepage": "https://corelicense.net",
   "repository": {
     "type": "git",
     "url": "https://github.com/trailanglc/corelicense.git",