@sidub-inc/licensing-client 1.5.57 → 1.5.72

package/README.md

@@ -11,7 +11,7 @@ npm install @sidub-inc/licensing-client
 **Requirements:**
 - Modern browsers with Web Crypto API support (Chrome, Firefox, Safari, Edge)
 - Node.js 18+ (or polyfill for `fetch` and `crypto.subtle`)
-- React 16.8+ (optional, for hooks)
+- React 16.8+ (optional, for `LicensingProvider` / `useLicensingContext`)
 
 ## Configuration
 
@@ -136,13 +136,13 @@ const result = await client.pollCheckoutResult(session.sessionId, {
 
 ### 5. Report Access Check (Telemetry)
 
+Telemetry-only: the event is always sent non-billable with a zero amount. Billable
+metering flows exclusively through `performOperation()`.
+
 ```typescript
-await client.reportAccessCheck(authorization, {
-  featureId: 'api-calls',
-  featureKey: 'api-calls',
-  IsBillable: true,
-  Amount: 1
-});
+// All parameters optional — defaults come from the resolved context/config.
+await client.reportAccessCheck();                        // configured license + feature context
+await client.reportAccessCheck('license-uuid', 'api-calls'); // explicit license + feature key
 ```
 
 ## Authorization Caching
@@ -230,9 +230,9 @@ const current = state.getConsumption(); // 2 (entries older than 60s are pruned)
 `RateLimitAssertion` consults local feature state before server-reported consumption:
 
 ```typescript
-// Store feature state on the client
-client.setFeatureState('api-calls', state);
-const stored = client.getFeatureState('api-calls');
+// Feature state is stored per license + feature key
+client.setFeatureState('license-uuid', 'api-calls', state);
+const stored = client.getFeatureState('license-uuid', 'api-calls');
 ```
 
 ## Assertions
@@ -259,17 +259,34 @@ const hasAccess = client.assertLicense(assertion, authorization);
 
 ### RateLimitAssertion
 
+Rate-limit assertions do NOT return `false` when the limit is exceeded — they **throw
+`RateLimitError`** (and emit an unconditional `console.warn`), matching the .NET SDK's
+`RateLimitException` contract. Handle the violation with try/catch:
+
 ```typescript
-import { RateLimitAssertion } from '@sidub-inc/licensing-client';
+import { RateLimitAssertion, RateLimitError } from '@sidub-inc/licensing-client';
 
 const assertion = RateLimitAssertion.create({
   featureId: 'api-calls',
   rateLimit: 1000,
   currentConsumption: 500
 });
-const withinLimit = client.assertLicense(assertion, authorization);
+
+try {
+  client.assertLicense(assertion, authorization); // true when within the limit
+  performTheRateLimitedWork();
+} catch (error) {
+  if (error instanceof RateLimitError) {
+    showUpgradePrompt(); // limit exhausted — the throw IS the enforcement signal
+  } else {
+    throw error;
+  }
+}
 ```
 
+The limit is inclusive: consumption equal to `rateLimit` still passes; the throw fires
+once consumption exceeds it.
+
 ### Composite Assertions
 
 ```typescript
@@ -313,89 +330,37 @@ function App() {
 }
 ```
 
-### useLicenseAuthorization
-
-```tsx
-import { useLicenseAuthorization } from '@sidub-inc/licensing-client';
-
-function LicensedComponent() {
-  const { 
-    authorization,      // LicenseAuthorization | null
-    loading,            // boolean
-    error,              // LicensingError | null
-    signatureValidated, // boolean
-    fetchAuthorization, // (licenseId?: string) => Promise<LicenseAuthorization>
-    clearAuthorization  // () => void
-  } = useLicenseAuthorization();
-
-  if (loading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
-  if (!authorization) return null;
-
-  return <div>License loaded {signatureValidated && '✓'}</div>;
-}
-```
-
-### useAssertion
-
-```tsx
-import { useLicenseAuthorization, useAssertion, ServiceAccessAssertion, ServiceAccessLevel } from '@sidub-inc/licensing-client';
-
-function FeatureGate() {
-  const { authorization } = useLicenseAuthorization();
-  const assertion = ServiceAccessAssertion.create('premium', ServiceAccessLevel.Allowed);
-  const hasPremium = useAssertion(assertion, authorization);
-
-  return hasPremium ? <PremiumFeature /> : <UpgradePrompt />;
-}
-```
-
-### useLicenseFeature
+### Using the Client from Context
 
-```tsx
-import { useLicenseAuthorization, useLicenseFeature } from '@sidub-inc/licensing-client';
-
-function Component() {
-  const { authorization } = useLicenseAuthorization();
-  const hasAnalytics = useLicenseFeature(authorization, 'analytics');
-
-  return hasAnalytics ? <Analytics /> : null;
-}
-```
-
-### useLicenseValidity
-
-```tsx
-import { useLicenseAuthorization, useLicenseValidity } from '@sidub-inc/licensing-client';
-
-function LicenseStatus() {
-  const { authorization } = useLicenseAuthorization();
-  const isValid = useLicenseValidity(authorization);
-
-  return <span>{isValid ? 'Active' : 'Expired'}</span>;
-}
-```
-
-### useReportConsumption
+The React surface is deliberately small: `LicensingProvider` owns one `LicensingClient`
+for the tree, and `useLicensingContext()` hands it to components. Everything else —
+authorization, assertions, consumption, checkout — is the same imperative client API
+documented above. (Earlier releases shipped per-concern hooks such as
+`useLicenseAuthorization`; they were removed in favor of the imperative client — see
+[MIGRATION.md](docs/MIGRATION.md).)
 
 ```tsx
-import { useLicensingContext, useReportConsumption } from '@sidub-inc/licensing-client';
+import { useLicensingContext, FeatureExistsAssertion } from '@sidub-inc/licensing-client';
+import { useEffect, useState } from 'react';
 
-function UsageTracker() {
+function FeatureGate({ children }: { children: React.ReactNode }) {
   const client = useLicensingContext();
-  const { reportConsumption, isReporting } = useReportConsumption(client);
-
-  const handleUse = async () => {
-    await reportConsumption({
-      licenseId: 'license-uuid',
-      feature: { featureId: 'api-calls' },
-      operationType: 'increment',
-      quantity: 1,
-      timestamp: new Date()
-    });
-  };
+  const [hasPremium, setHasPremium] = useState<boolean | null>(null);
 
-  return <button onClick={handleUse} disabled={isReporting}>Track Usage</button>;
+  useEffect(() => {
+    let cancelled = false;
+    client.getAuthorization()
+      .then(authorization => {
+        if (cancelled) return;
+        const assertion = FeatureExistsAssertion.create('premium');
+        setHasPremium(client.assertLicense(assertion, authorization));
+      })
+      .catch(() => !cancelled && setHasPremium(false));
+    return () => { cancelled = true; };
+  }, [client]);
+
+  if (hasPremium === null) return <div>Loading…</div>;
+  return hasPremium ? <>{children}</> : <UpgradePrompt />;
 }
 ```
 
@@ -456,19 +421,19 @@ function PurchaseButton({ offeringId }: { offeringId: string }) {
 
 `pollCheckoutResult()` uses exponential backoff (1s initial, doubling to 15s cap, 60 max attempts ~15 min total). Pass an `AbortSignal` to cancel polling. Throws `LicensingError` on timeout or cancellation.
 
-### Standalone Hook (without Provider)
+### Without the Provider
 
-```tsx
-import { useLicensing } from '@sidub-inc/licensing-client';
+Outside React (Node services, plain scripts) or when a component tree does not need a
+shared context, construct `LicensingClient` directly — the Provider is a convenience,
+not a requirement:
 
-function Component() {
-  const client = useLicensing({
-    licenseServiceUri: 'https://api.monaiq.com/licensing',
-    encodedCredential: 'SIDUB_LIC_...'
-  });
+```typescript
+import { LicensingClient } from '@sidub-inc/licensing-client';
 
-  // Use client directly
-}
+const client = new LicensingClient({
+  licenseServiceUri: 'https://api.monaiq.com/licensing',
+  encodedCredential: 'SIDUB_LIC_...'
+});
 ```
 
 ## Signature Validation
@@ -513,6 +478,7 @@ const decoded = decodeCredential(encoded);     // LicensingCredential
 | `LicensingError` | Base error for API, network, and timeout errors |
 | `LicensingConfigurationException` | Missing required configuration fields (extends `LicensingError`) |
 | `CryptoError` | Signature validation failures (`KEY_IMPORT_FAILED`, `VERIFICATION_FAILED`, `INVALID_SIGNATURE`) |
+| `RateLimitError` | Thrown by `assertLicense` when a `RateLimitAssertion` limit is exceeded — catch it; it is the enforcement signal, not a failure |
 
 ```typescript
 import { LicensingError, LicensingConfigurationException, CryptoError } from '@sidub-inc/licensing-client';