@sidub-inc/licensing-client 1.3.43

package/README.md

@@ -0,0 +1,559 @@
+# @sidub-inc/licensing-client
+
+TypeScript/React runtime library for Sidub Licensing. Provides license enforcement, feature gating, consumption reporting, and cryptographic signature verification.
+
+## Installation
+
+```bash
+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)
+
+## Configuration
+
+### Using Encoded Credentials (Recommended)
+
+Encoded credentials bundle all required values into a single portable string:
+
+```typescript
+import { LicensingClient } from '@sidub-inc/licensing-client';
+
+const client = new LicensingClient({
+  licenseServiceUri: 'https://api.monaiq.com/licensing',
+  encodedCredential: 'SIDUB_LIC_eyJ...'  // From your license portal
+});
+```
+
+The encoded credential contains: `licenseId`, `serviceKeyId`, `serviceKeyPublicMember`, and `apiAccessKey`.
+
+### Manual Configuration
+
+```typescript
+const client = new LicensingClient({
+  licenseServiceUri: 'https://api.monaiq.com/licensing',
+  apiKey: 'your-api-key',
+  licenseId: 'your-license-uuid',                    // Optional if passed to getAuthorization()
+  serviceKeyId: 'your-service-key-uuid',             // Required for signature validation
+  serviceKeyPublicMember: 'base64-encoded-public-key' // Required for signature validation
+});
+```
+
+### Configuration Reference
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `licenseServiceUri` | Yes | Base URI for the licensing API |
+| `encodedCredential` | No | Encoded credential string (SIDUB_LIC_...) |
+| `apiKey` | No | API authentication key |
+| `licenseId` | No | Default license ID |
+| `serviceKeyId` | No | Key ID for signature verification |
+| `serviceKeyPublicMember` | No | Base64 EC public key (P-256 SPKI) for signature verification |
+| `consumptionServiceUri` | No | Separate URI for consumption reporting |
+| `timeout` | No | Request timeout in ms (default: 30000) |
+| `validateSignatures` | No | Enable/disable signature validation (default: auto) |
+| `cacheEnabled` | No | Enable authorization caching (default: true) |
+| `cacheMaxSize` | No | Maximum cached authorizations (default: 100) |
+| `contextProvider` | No | Custom `ILicensingContextProvider` for credential resolution |
+| `billableResourceId` | No | Billable resource ID for consumption reporting |
+| `billablePlanId` | No | Billable plan ID for consumption reporting |
+
+## Core Operations
+
+### 1. Get License Authorization
+
+```typescript
+// Using configured license ID
+const authorization = await client.getAuthorization();
+
+// With explicit license ID
+const authorization = await client.getAuthorization('license-uuid');
+
+// Authorization includes:
+// - licenseId, classification, features[], issuedAt, expiresAt
+// - signature (if server-signed)
+// - signatureValidated (true if cryptographic verification passed)
+```
+
+### 2. Assert License Conditions
+
+```typescript
+import { ServiceAccessAssertion, ServiceAccessLevel } from '@sidub-inc/licensing-client';
+
+const assertion = ServiceAccessAssertion.create('premium-feature', ServiceAccessLevel.Allowed);
+const hasAccess = client.assertLicense(assertion, authorization);
+```
+
+### 3. Report Consumption
+
+```typescript
+await client.performOperation({
+  licenseId: 'license-uuid',
+  feature: { featureId: 'api-calls' },
+  operationType: 'increment',
+  quantity: 1,
+  timestamp: new Date()
+});
+```
+
+### 4. Checkout Flow
+
+Create embedded checkout sessions for purchasing offerings:
+
+```typescript
+// Create a checkout session
+const session = await client.createCheckoutSession({
+  offeringId: 'offering-uuid',
+  issuerClientId: 'issuer-uuid',
+  correlationId: 'correlation-uuid',
+  customerEmail: 'user@example.com',
+  successUrl: 'https://example.com/success',
+  cancelUrl: 'https://example.com/cancel'
+});
+
+// For paid offerings, redirect to payment
+if (session.sessionUrl) {
+  window.location.href = session.sessionUrl;
+}
+
+// Poll for checkout result
+const result = await client.getCheckoutResult(session.sessionId);
+// result.status: 'pending' | 'completed' | 'failed'
+// result.encodedCredential: SIDUB_LIC_... (on completion)
+
+// Poll with exponential backoff (recommended for full lifecycle)
+const result = await client.pollCheckoutResult(session.sessionId, {
+  maxAttempts: 60,    // default: 60
+  signal: abortController.signal  // optional: cancel polling
+});
+// result.status: 'completed' | 'failed'
+// result.encodedCredential: SIDUB_LIC_... (on completion)
+// Throws LicensingError if max attempts exceeded or signal aborted
+```
+
+### 5. Report Access Check (Telemetry)
+
+```typescript
+await client.reportAccessCheck(authorization, {
+  featureId: 'api-calls',
+  featureKey: 'api-calls',
+  IsBillable: true,
+  Amount: 1
+});
+```
+
+## Authorization Caching
+
+Authorization responses are cached in memory with TTL-based expiry (derived from `expiresAt`). Caching is enabled by default.
+
+```typescript
+const client = new LicensingClient({
+  licenseServiceUri: '...',
+  encodedCredential: '...',
+  cacheEnabled: true,   // default
+  cacheMaxSize: 100     // default
+});
+
+// Manual cache management
+client.clearCache();                    // Remove all cached authorizations
+client.invalidateCache('license-uuid'); // Remove entries for a specific license
+```
+
+When caching is enabled, repeated calls to `getAuthorization()` with the same license ID return the cached result until it expires.
+
+## Context Providers
+
+Context providers resolve licensing credentials dynamically, supporting multi-tenant scenarios.
+
+### ConfigurationContextProvider (Default)
+
+Builds context from `LicensingConfig` fields. Used automatically when no custom provider is configured:
+
+```typescript
+import { ConfigurationContextProvider } from '@sidub-inc/licensing-client';
+
+const provider = new ConfigurationContextProvider(config);
+const context = await provider.resolveContext();
+// context: { licenseId, serviceKeyId, serviceKeyPublicMember, apiAccessKey, billableResourceId?, billablePlanId? }
+```
+
+### Custom Context Provider
+
+Implement `ILicensingContextProvider` for custom resolution strategies (e.g., per-tenant lookup):
+
+```typescript
+import { ILicensingContextProvider, LicensingContextType } from '@sidub-inc/licensing-client';
+
+class TenantContextProvider implements ILicensingContextProvider {
+  async resolveContext(): Promise<LicensingContextType | null> {
+    const tenantCreds = await fetchTenantCredentials();
+    if (!tenantCreds) return null;
+    return {
+      licenseId: tenantCreds.licenseId,
+      serviceKeyId: tenantCreds.serviceKeyId,
+      serviceKeyPublicMember: tenantCreds.publicKey,
+      apiAccessKey: tenantCreds.apiKey
+    };
+  }
+}
+```
+
+### Portable Encoded Credentials
+
+```typescript
+import { licensingContextFromEncodedString, licensingContextToEncodedString } from '@sidub-inc/licensing-client';
+
+// Decode an encoded credential string into a context
+const context = licensingContextFromEncodedString('SIDUB_LIC_eyJ...', billableResourceId, billablePlanId);
+
+// Encode a context back to a portable string (billable fields are not included)
+const encoded = licensingContextToEncodedString(context);
+```
+
+## Feature State (Rate Limiting)
+
+Track local rate-limit consumption within time windows:
+
+```typescript
+import { RateLimitFeatureState } from '@sidub-inc/licensing-client';
+
+// Track consumption within a 60-second window
+const state = new RateLimitFeatureState(60);
+state.consumeRate(1);
+state.consumeRate(1);
+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');
+```
+
+## Assertions
+
+Assertions provide declarative license condition checking.
+
+### FeatureExistsAssertion
+
+```typescript
+import { FeatureExistsAssertion } from '@sidub-inc/licensing-client';
+
+const assertion = FeatureExistsAssertion.create('analytics');
+const hasFeature = client.assertLicense(assertion, authorization);
+```
+
+### ServiceAccessAssertion
+
+```typescript
+import { ServiceAccessAssertion, ServiceAccessLevel } from '@sidub-inc/licensing-client';
+
+const assertion = ServiceAccessAssertion.create('api-access', ServiceAccessLevel.Allowed);
+const hasAccess = client.assertLicense(assertion, authorization);
+```
+
+### RateLimitAssertion
+
+```typescript
+import { RateLimitAssertion } from '@sidub-inc/licensing-client';
+
+const assertion = RateLimitAssertion.create({
+  featureId: 'api-calls',
+  rateLimit: 1000,
+  currentConsumption: 500
+});
+const withinLimit = client.assertLicense(assertion, authorization);
+```
+
+### Composite Assertions
+
+```typescript
+import { CompositeAssertion, FeatureExistsAssertion } from '@sidub-inc/licensing-client';
+
+// AND: all must be satisfied
+const both = CompositeAssertion.and(
+  FeatureExistsAssertion.create('feature1'),
+  FeatureExistsAssertion.create('feature2')
+);
+
+// OR: any must be satisfied
+const either = CompositeAssertion.or(
+  FeatureExistsAssertion.create('feature1'),
+  FeatureExistsAssertion.create('feature2')
+);
+
+// NOT: invert result
+import { NotAssertion } from '@sidub-inc/licensing-client';
+const notBlocked = NotAssertion.create(FeatureExistsAssertion.create('blocked'));
+```
+
+## React Integration
+
+### Provider Setup
+
+```tsx
+import { LicensingProvider } from '@sidub-inc/licensing-client';
+
+function App() {
+  return (
+    <LicensingProvider 
+      config={{ 
+        licenseServiceUri: 'https://api.monaiq.com/licensing',
+        encodedCredential: process.env.REACT_APP_LICENSE_CREDENTIAL
+      }}
+    >
+      <YourApp />
+    </LicensingProvider>
+  );
+}
+```
+
+### 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
+
+```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
+
+```tsx
+import { useLicensingContext, useReportConsumption } from '@sidub-inc/licensing-client';
+
+function UsageTracker() {
+  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()
+    });
+  };
+
+  return <button onClick={handleUse} disabled={isReporting}>Track Usage</button>;
+}
+```
+
+### Checkout Lifecycle (pollCheckoutResult)
+
+Use `pollCheckoutResult()` on `LicensingClient` for the full checkout lifecycle with exponential backoff:
+
+```tsx
+import { useLicensingContext } from '@sidub-inc/licensing-client';
+
+function PurchaseButton({ offeringId }: { offeringId: string }) {
+  const client = useLicensingContext();
+  const [status, setStatus] = useState<'idle' | 'processing' | 'completed' | 'failed'>('idle');
+  const [result, setResult] = useState<CheckoutSessionResult | null>(null);
+  const controllerRef = useRef<AbortController | null>(null);
+
+  const handlePurchase = async () => {
+    setStatus('processing');
+    try {
+      const session = await client.createCheckoutSession({
+        offeringId,
+        issuerClientId: 'issuer-uuid',
+        correlationId: crypto.randomUUID(),
+        customerEmail: 'user@example.com',
+        successUrl: window.location.origin + '/success',
+        cancelUrl: window.location.origin + '/cancel'
+      });
+
+      // For paid offerings, redirect to payment
+      if (session.sessionUrl) {
+        window.location.href = session.sessionUrl;
+        return;
+      }
+
+      // For free/trial offerings, poll for result
+      controllerRef.current = new AbortController();
+      const checkoutResult = await client.pollCheckoutResult(session.sessionId, {
+        signal: controllerRef.current.signal,
+        maxAttempts: 60  // ~15 min with exponential backoff (1s → 15s cap)
+      });
+      setResult(checkoutResult);
+      setStatus(checkoutResult.status === 'completed' ? 'completed' : 'failed');
+    } catch (error) {
+      setStatus('failed');
+    }
+  };
+
+  useEffect(() => {
+    return () => controllerRef.current?.abort();
+  }, []);
+
+  if (status === 'completed') return <div>Purchase complete! License: {result?.licenseId}</div>;
+  if (status === 'failed') return <div>Error occurred <button onClick={() => setStatus('idle')}>Retry</button></div>;
+
+  return <button onClick={handlePurchase} disabled={status === 'processing'}>Purchase</button>;
+}
+```
+
+`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)
+
+```tsx
+import { useLicensing } from '@sidub-inc/licensing-client';
+
+function Component() {
+  const client = useLicensing({
+    licenseServiceUri: 'https://api.monaiq.com/licensing',
+    encodedCredential: 'SIDUB_LIC_...'
+  });
+
+  // Use client directly
+}
+```
+
+## Signature Validation
+
+When `serviceKeyId` and `serviceKeyPublicMember` are configured (directly or via encoded credential), the library validates authorization signatures using ECDSA with P-256 (secp256r1) and SHA-256.
+
+**Validation flow:**
+1. Server signs `LicenseAuthorization` with private EC key (P-256)
+2. Client receives authorization with `signature` field
+3. Client verifies signature using configured public key
+4. Invalid signatures throw `CryptoError`
+
+**Disable validation (not recommended):**
+```typescript
+const client = new LicensingClient({
+  licenseServiceUri: '...',
+  encodedCredential: '...',
+  validateSignatures: false
+});
+```
+
+## Credential Encoding
+
+```typescript
+import { encodeCredential, decodeCredential, LicensingCredential } from '@sidub-inc/licensing-client';
+
+const credential: LicensingCredential = {
+  licenseId: 'uuid',
+  serviceKeyId: 'uuid',
+  serviceKeyPublicMember: 'base64-key',
+  apiAccessKey: 'api-key'
+};
+
+const encoded = encodeCredential(credential);  // "SIDUB_LIC_eyJ..."
+const decoded = decodeCredential(encoded);     // LicensingCredential
+```
+
+## Error Handling
+
+| Error Type | Description |
+|-----------|-------------|
+| `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`) |
+
+```typescript
+import { LicensingError, LicensingConfigurationException, CryptoError } from '@sidub-inc/licensing-client';
+
+try {
+  const authorization = await client.getAuthorization();
+} catch (error) {
+  if (error instanceof CryptoError) {
+    // Signature validation failed
+    console.error('Signature invalid:', error.code);
+  } else if (error instanceof LicensingConfigurationException) {
+    // Missing configuration
+    console.error('Config error:', error.message);
+  } else if (error instanceof LicensingError) {
+    // API or network error
+    console.error('Licensing error:', error.message, error.statusCode);
+  }
+}
+```
+
+## TypeScript Types
+
+```typescript
+import type {
+  LicensingConfig,
+  LicenseAuthorization,
+  LicensingCredential,
+  ILicenseFeature,
+  LicenseClassificationType,
+  ILicenseAssertion
+} from '@sidub-inc/licensing-client';
+```
+
+## Migrating from v1.0.x
+
+See [MIGRATION.md](docs/MIGRATION.md) for detailed upgrade instructions. Key changes:
+- `BillingIntervalUnit` enum members renamed: `Days`→`Day`, `Months`→`Month`, `Years`→`Year` (+ new `Hour`, `Week`)
+- `performOperation()` payload structure changed (nested `LicenseOperation`)
+- Configuration validation now throws `LicensingConfigurationException` instead of `LicensingError`
+- Consumption requests use `dub-apiKey` header (was `dub-issuerKey`)
+
+## License
+
+MIT © Sidub Inc.