@kelviq/js-sdk 1.0.0 → 2.0.0-beta

package/README.md

@@ -1,15 +1,15 @@
----
-title: "JavaScript SDK"
-description: "Documentation for the Kelviq JavaScript SDK"
-icon: "js"
----
+# @kelviq/js-sdk
 
-The `@kelviq/js-sdk` is a lightweight, plain TypeScript library designed for interacting with the Kelviq entitlement service. It allows you to:
+A lightweight TypeScript SDK for integrating with the Kelviq entitlement service. Easily check feature access, retrieve entitlement details, and manage client-side caching for your application.
 
-- Fetch all feature entitlements for a specific organization and customer.
-- Cache these entitlements client-side for efficient and repeated access.
-- Check if a user has access to a particular feature.
-- Retrieve specific entitlement details, including boolean flags, numeric configurations, and metered usage data.
-- Manually refresh entitlement data from the server.
+## Installation
 
-### Docs - https://docs.kelviq.com/frontend-integration/js-sdk
+```bash
+npm install @kelviq/js-sdk
+```
+
+## Documentation
+
+For full usage instructions, API reference, and examples, visit the official docs:
+
+**[https://docs.kelviq.com/frontend-integration/js-sdk](https://docs.kelviq.com/frontend-integration/js-sdk)**

package/dist/index.d.ts

@@ -1,27 +1,30 @@
 // Generated by dts-bundle-generator v9.5.1
 
-export interface Entitlement {
+export interface RawEntitlement {
 	featureId: string;
+	featureType: "BOOLEAN" | "CUSTOMIZABLE" | "METER";
 	hasAccess: boolean;
-	type: "boolean" | "customizable" | "metered";
-}
-export interface BooleanEntitlement extends Entitlement {
-	type: "boolean";
+	resetAt?: string | null;
+	hardLimit?: boolean;
+	usageLimit?: number | null;
+	currentUsage?: number;
+	remaining?: number | null;
 }
-export interface ConfigEntitlement extends Entitlement {
-	type: "customizable";
-	configuration: number | null;
+export interface RawEntitlementsApiResponse {
+	customer_id: string;
+	entitlements: RawEntitlement[];
 }
-export interface MeteredEntitlement extends Entitlement {
-	type: "metered";
-	limit: number | null;
-	used: number;
+export interface Entitlement {
+	featureId: string;
+	featureType: "METER" | "BOOLEAN" | "CUSTOMIZABLE";
+	hasAccess: boolean;
+	hardLimit: boolean;
+	currentUsage: number;
+	usageLimit: number | null;
 	remaining: number | null;
-	resetAt?: string | null;
-	hardLimit?: boolean;
+	items: RawEntitlement[];
 }
-export type AnyEntitlement = BooleanEntitlement | ConfigEntitlement | MeteredEntitlement;
-export type EntitlementMap = Record<string, AnyEntitlement>;
+export type EntitlementMap = Record<string, Entitlement>;
 /**
  * Configuration for an API request.
  * @template ReqBody The type of the request body.
@@ -95,53 +98,63 @@ declare function apiRequest<ResData = any, ReqBody = any>(config: ApiRequestConf
 declare class KelviqClient {
 	private readonly options;
 	private entitlementsCache;
+	private rawApiResponse;
 	private isFetching;
+	private inFlightPromise;
+	private readyPromise;
 	private lastFetchError;
 	private readonly apiRequestService;
 	/**
 	 * Creates an instance of KelviqClient.
-	 * Prefer using the `createKelviqClient` factory function for instantiation.
+	 * Prefer using the `kelviqSDK` factory function for instantiation.
 	 * @internal
 	 * @param options Configuration options for the client.
 	 * @param customApiRequest Optional: A custom function to handle API requests, conforming to ApiRequestConfig and ApiResponse.
 	 */
 	constructor(options: KelviqClientOptions, customApiRequest?: typeof apiRequest);
 	/**
-	 * Fetches all entitlements from the API for the configured orgId and customerId,
+	 * Fetches all entitlements from the API for the configured customerId,
 	 * processes them, and caches the result.
 	 * Subsequent calls will return cached data unless `forceRefresh` is true.
 	 *
 	 * @param forceRefresh - If true, fetches from the API even if data is already cached. Defaults to false.
-	 * @returns A promise that resolves to the map of entitlements (EntitlementMap).
+	 * @returns A promise that resolves to the map of aggregated entitlements.
 	 * @throws Will throw an error if the API request fails after all retries.
 	 */
 	fetchAllEntitlements(forceRefresh?: boolean): Promise<EntitlementMap>;
 	/**
-	 * Retrieves a specific entitlement from the local cache.
-	 * Note: `fetchAllEntitlements()` must be called successfully at least once before using this method,
-	 * or the cache will be empty.
+	 * Retrieves a specific aggregated entitlement from the local cache.
 	 *
-	 * @param featureId The unique key of the feature.
-	 * @param type The expected type of the entitlement ('boolean', 'config', 'metered').
-	 * @returns The processed entitlement object if found in the cache and the type matches, otherwise `null`.
-	 * Logs a warning if entitlements haven't been fetched or if a type mismatch occurs.
+	 * @param featureId The unique identifier of the feature.
+	 * @returns The aggregated Entitlement object if found, otherwise `null`.
 	 */
-	getEntitlement<T extends AnyEntitlement>(featureId: string, type: T["type"]): T | null;
+	getEntitlement(featureId: string): Entitlement | null;
 	/**
-	 * Checks if the user has access to a specific feature based on cached entitlements.
-	 * Note: `fetchAllEntitlements()` should be called successfully at least once before using this method.
+	 * Returns all aggregated entitlements as a map keyed by featureId.
 	 *
-	 * @param featureId The key of the feature.
-	 * @returns `true` if access is granted, `false` if denied or the feature is not found in the cache.
-	 * Logs a warning and returns `false` if entitlements haven't been fetched.
+	 * @returns Record of featureId to aggregated Entitlement, or `null` if not fetched.
 	 */
-	hasAccess(featureId: string): boolean;
+	getEntitlements(): EntitlementMap | null;
+	/**
+	 * Returns the raw API items for a specific featureId (un-aggregated).
+	 *
+	 * @param featureId The unique identifier of the feature.
+	 * @returns Array of raw entitlement items for the given featureId, or `null` if not fetched.
+	 */
+	getRawEntitlement(featureId: string): RawEntitlement[] | null;
+	/**
+	 * Returns the full raw API response including the customer_id wrapper.
+	 *
+	 * @returns The raw API response `{ customer_id, entitlements }`, or `null` if not fetched.
+	 */
+	getRawEntitlements(): RawEntitlementsApiResponse | null;
 	/**
-	 * Returns the currently cached map of all entitlements.
-	 * `fetchAllEntitlements()` should be called successfully at least once.
-	 * @returns The EntitlementMap (a record of featureKey to entitlement data) or `null` if not fetched or an error occurred during the last fetch.
+	 * Checks if the user has access to a specific feature based on cached entitlements.
+	 *
+	 * @param featureId The identifier of the feature.
+	 * @returns `true` if access is granted, `false` otherwise.
 	 */
-	getAllEntitlements(): EntitlementMap | null;
+	hasAccess(featureId: string): boolean;
 	/**
 	 * Indicates if an entitlement fetch operation is currently in progress.
 	 * @returns `true` if a fetch is in progress, `false` otherwise.
@@ -152,9 +165,17 @@ declare class KelviqClient {
 	 * @returns An `Error` object if the last fetch failed, otherwise `null`.
 	 */
 	getLastError(): Error | null;
+	/**
+	 * Returns a promise that resolves when the initial fetch (triggered by `initializeAndFetch: true`) completes.
+	 * If no initial fetch was triggered, resolves immediately.
+	 */
+	ready(): Promise<void>;
+	/**
+	 * @internal Sets the ready promise. Called by the factory when initializeAndFetch is true.
+	 */
+	_setReadyPromise(promise: Promise<void>): void;
 	/**
 	 * Clears the local entitlement cache and resets loading and error states.
-	 * After calling this, `fetchAllEntitlements()` will need to be called again to populate the cache.
 	 */
 	clearCache(): void;
 }
@@ -165,8 +186,7 @@ declare class KelviqClient {
  * @param customApiRequest Optional: A custom function to handle API requests, useful for testing or custom HTTP clients.
  * @returns An instance of KelviqClient.
  */
-declare function kelviqSDK(// Renamed from createKelviqClient
-options: KelviqClientOptions, customApiRequest?: typeof apiRequest): KelviqClient;
+declare function kelviqSDK(options: KelviqClientOptions, customApiRequest?: typeof apiRequest): KelviqClient;
 
 export {
 	kelviqSDK as default,

package/dist/kelviq-js-sdk.iife.js

@@ -1 +1 @@
-var kelviqSDK=function(){"use strict";var P=Object.defineProperty;var b=(d,m,y)=>m in d?P(d,m,{enumerable:!0,configurable:!0,writable:!0,value:y}):d[m]=y;var A=(d,m,y)=>b(d,typeof m!="symbol"?m+"":m,y);function d(s){const n={};return!s||!Array.isArray(s.entitlements)?(console.warn("[Kelviq SDK] transformApiEntitlements: Invalid or empty entitlements array in API response.",s),n):(s.entitlements.forEach(e=>{if(!e||typeof e.featureId!="string"||typeof e.featureType!="string"){console.warn("[Kelviq SDK] transformApiEntitlements: Skipping invalid raw entitlement object:",e);return}let t=null;const f={featureId:e.featureId,hasAccess:e.hasAccess};if(e.featureType==="BOOLEAN")t={...f,type:"boolean"};else if(e.featureType==="CUSTOMIZABLE"){const r=e;t={...f,type:"customizable",configuration:typeof r.value=="number"?r.value:null}}else if(e.featureType==="METER"){const r=e,E=typeof r.usageLimit=="number"?r.usageLimit:null,o=typeof r.currentUsage=="number"?r.currentUsage:0;t={...f,type:"metered",limit:E,used:o,remaining:E!==null?E-o:null,resetAt:r.resetAt,hardLimit:r.hardLimit}}else{const r=e;console.warn(`[Kelviq SDK] transformApiEntitlements: Encountered unknown or unhandled entitlement featureType: '${String(r.featureType)}' for feature '${String(r.feature)}'. This entitlement will be ignored.`)}t&&(n[t.featureId]=t)}),n)}const m="GET",y=5e3,R=3,$=1e3;function F(s){const{method:n=m,headers:e={},body:t,timeout:f=y,maxRetries:r=R,backoffBaseDelay:E=$,queryParams:o,accessToken:v}=s;let a=s.url,g=0;return new Promise((T,l)=>{if(o){const c=new URLSearchParams;for(const p in o)o[p]!==void 0&&c.append(p,String(o[p]));c.toString()&&(a=a+(a.includes("?")?"&":"?")+c.toString())}function u(){const c=new XMLHttpRequest;c.open(n,a,!0),c.timeout=f;const p={Accept:"application/json","X-Requested-With":"XMLHttpRequest",...e};n!=="GET"&&t&&typeof t=="object"&&!(t instanceof FormData)&&(p["Content-Type"]||(p["Content-Type"]="application/json")),v&&(p.Authorization=`Bearer ${v}`);for(const[i,h]of Object.entries(p))c.setRequestHeader(i,h);c.onload=function(){const{status:i,statusText:h,responseText:S}=c;if(i>=200&&i<300)try{const q=S?JSON.parse(S):{};T({status:i,statusText:h,data:q})}catch(q){const D=q instanceof Error?q:new Error(String(q));console.error(`Kelviq SDK (apiRequest): Invalid JSON response for URL ${a}. Error: ${D.message}. Response: ${S}`),l(new Error(`Invalid JSON response: ${D.message}`))}else K(`Request to ${a} failed with status ${i} ${h}. Response: ${S}`)},c.onerror=()=>K(`Network error for URL ${a}. The request could not be completed.`),c.ontimeout=()=>K(`Request to ${a} timed out.`);function K(i){if(g<r){g++;const h=Math.min(E*Math.pow(2,g-1),3e4);console.warn(`Kelviq SDK (apiRequest): Retrying request to ${a}. Attempt ${g}/${r}. Error: ${i}. Retrying in ${h}ms.`),setTimeout(u,h)}else l(new Error(`${i} (Max retries ${r} reached)`))}try{let i=t;t&&typeof t=="object"&&!(t instanceof FormData)&&p["Content-Type"]==="application/json"&&(i=JSON.stringify(t)),c.send(i)}catch(i){const h=i instanceof Error?i:new Error(String(i));console.error(`Kelviq SDK (apiRequest): Error sending request to ${a}.`,h),l(new Error(`Failed to send request: ${h.message}`))}}u()})}const L="https://edge.api.kelviq.com/api/v1/",w="https://edge.sandboxapi.kelviq.com/api/v1/",C="entitlements/";class I{constructor(n,e){A(this,"options");A(this,"entitlementsCache",null);A(this,"isFetching",!1);A(this,"lastFetchError",null);A(this,"apiRequestService");if(!n||!n.customerId)throw new Error("[Kelviq SDK] KelviqClient: CustomerId is required in options.");this.options={...n,apiConfig:n.apiConfig||{},entitlementsPath:n.entitlementsPath||C},this.apiRequestService=e||F}async fetchAllEntitlements(n=!1){if(this.isFetching)return Promise.reject(new Error("[Kelviq SDK] An entitlement fetch is already in progress."));if(this.entitlementsCache&&!n)return Promise.resolve(this.entitlementsCache);this.isFetching=!0,this.lastFetchError=null;const{apiUrl:e=this.options.environment==="sandbox"?w:L,entitlementsPath:t,customerId:f,accessToken:r,apiConfig:E,onError:o}=this.options,v=e.replace(/\/$/,""),a=t.replace(/^\//,""),g=`${v}/${a}`,T={customer_id:f};try{const l=await this.apiRequestService({url:g,method:"GET",queryParams:T,accessToken:r,...E||{}});if(l&&l.data&&Array.isArray(l.data.entitlements))return this.entitlementsCache=d(l.data),this.isFetching=!1,this.entitlementsCache;{const u=new Error("[Kelviq SDK] Received empty, malformed, or invalid data structure from entitlements API.");throw this.lastFetchError=u,this.isFetching=!1,this.entitlementsCache=null,o&&o(u),u}}catch(l){const u=l instanceof Error?l:new Error(String(l));throw this.lastFetchError=u,this.isFetching=!1,this.entitlementsCache=null,o&&o(u),u}}getEntitlement(n,e){if(!this.entitlementsCache)return console.warn(`[Kelviq SDK] getEntitlement: Entitlements not fetched or cache is empty for featureId '${n}'. Call fetchAllEntitlements() first.`),null;const t=this.entitlementsCache[n];return t?t.type===e?t:(console.warn(`[Kelviq SDK] getEntitlement: Type mismatch for featureId '${n}'. Expected type '${e}', but cached type is '${t.type}'.`),null):null}hasAccess(n){if(!this.entitlementsCache)return console.warn(`[Kelviq SDK] hasAccess: Entitlements not fetched yet for featureId '${n}'. Call fetchAllEntitlements() first. Returning false.`),!1;const e=this.entitlementsCache[n];return e?e.hasAccess:!1}getAllEntitlements(){return this.entitlementsCache}isLoading(){return this.isFetching}getLastError(){return this.lastFetchError}clearCache(){this.entitlementsCache=null,this.isFetching=!1,this.lastFetchError=null,console.log("[Kelviq SDK] Entitlement cache cleared.")}}function U(s,n){const e={...s,initializeAndFetch:s.initializeAndFetch||!0,apiConfig:s.apiConfig||{},environment:s.environment||"production",entitlementsPath:s.entitlementsPath||C},t=new I(e,n);return e.initializeAndFetch===!0&&t.fetchAllEntitlements().catch(f=>{console.error("[Kelviq SDK] Initial fetch on client creation failed:",f.message)}),t}return U}();
+var kelviqSDK=function(){"use strict";var I=Object.defineProperty;var _=(y,d,q)=>d in y?I(y,d,{enumerable:!0,configurable:!0,writable:!0,value:q}):y[d]=q;var E=(y,d,q)=>_(y,typeof d!="symbol"?d+"":d,q);function y(a){const e={};if(!a||!Array.isArray(a.entitlements))return console.warn("[Kelviq SDK] transformApiEntitlements: Invalid or empty entitlements array in API response.",a),e;const i={};a.entitlements.forEach(t=>{if(!t||typeof t.featureId!="string"||typeof t.featureType!="string"){console.warn("[Kelviq SDK] transformApiEntitlements: Skipping invalid raw entitlement object:",t);return}i[t.featureId]||(i[t.featureId]=[]),i[t.featureId].push(t)});for(const t of Object.keys(i)){const c=i[t],u=c[0].featureType;let A=0,r=null,f=null,l=!1,m=!1;if(u==="METER"){let n=!0;for(const s of c)A+=typeof s.currentUsage=="number"?s.currentUsage:0,typeof s.usageLimit=="number"&&(r=(r??0)+s.usageLimit,n=!1);n&&(r=null),f=r!==null?r-A:null,l=c.some(s=>s.hardLimit===!0),m=f===null||f>0}else if(u==="CUSTOMIZABLE"){const n=c[0];r=typeof n.usageLimit=="number"?n.usageLimit:null,A=typeof n.currentUsage=="number"?n.currentUsage:0,f=typeof n.remaining=="number"?n.remaining:null,l=n.hardLimit===!0,m=c.some(s=>s.hasAccess)}else if(u==="BOOLEAN")m=c.some(n=>n.hasAccess);else{console.warn(`[Kelviq SDK] transformApiEntitlements: Encountered unknown featureType: '${u}' for feature '${t}'. This entitlement will be ignored.`);continue}const R={featureId:t,featureType:u,hasAccess:m,hardLimit:l,currentUsage:A,usageLimit:r,remaining:f,items:c};e[t]=R}return e}const d="GET",q=5e3,K=3,P=1e3;function C(a){const{method:e=d,headers:i={},body:t,timeout:c=q,maxRetries:u=K,backoffBaseDelay:A=P,queryParams:r,accessToken:f}=a;let l=a.url,m=0;return new Promise((R,n)=>{if(r){const h=new URLSearchParams;for(const g in r)r[g]!==void 0&&h.append(g,String(r[g]));h.toString()&&(l=l+(l.includes("?")?"&":"?")+h.toString())}function s(){const h=new XMLHttpRequest;h.open(e,l,!0),h.timeout=c;const g={Accept:"application/json","X-Requested-With":"XMLHttpRequest",...i};e!=="GET"&&t&&typeof t=="object"&&!(t instanceof FormData)&&(g["Content-Type"]||(g["Content-Type"]="application/json")),f&&(g.Authorization=`Bearer ${f}`);for(const[o,p]of Object.entries(g))h.setRequestHeader(o,p);h.onload=function(){const{status:o,statusText:p,responseText:F}=h;if(o>=200&&o<300)try{const v=F?JSON.parse(F):{};R({status:o,statusText:p,data:v})}catch(v){const w=v instanceof Error?v:new Error(String(v));console.error(`Kelviq SDK (apiRequest): Invalid JSON response for URL ${l}. Error: ${w.message}. Response: ${F}`),n(new Error(`Invalid JSON response: ${w.message}`))}else S(`Request to ${l} failed with status ${o} ${p}. Response: ${F}`)},h.onerror=()=>S(`Network error for URL ${l}. The request could not be completed.`),h.ontimeout=()=>S(`Request to ${l} timed out.`);function S(o){if(m<u){m++;const p=Math.min(A*Math.pow(2,m-1),3e4);console.warn(`Kelviq SDK (apiRequest): Retrying request to ${l}. Attempt ${m}/${u}. Error: ${o}. Retrying in ${p}ms.`),setTimeout(s,p)}else n(new Error(`${o} (Max retries ${u} reached)`))}try{let o=t;t&&typeof t=="object"&&!(t instanceof FormData)&&g["Content-Type"]==="application/json"&&(o=JSON.stringify(t)),h.send(o)}catch(o){const p=o instanceof Error?o:new Error(String(o));console.error(`Kelviq SDK (apiRequest): Error sending request to ${l}.`,p),n(new Error(`Failed to send request: ${p.message}`))}}s()})}const L="https://edge.api.kelviq.com/api/v1/",D="https://edge.sandboxapi.kelviq.com/api/v1/",T="entitlements/";class ${constructor(e,i){E(this,"options");E(this,"entitlementsCache",null);E(this,"rawApiResponse",null);E(this,"isFetching",!1);E(this,"inFlightPromise",null);E(this,"readyPromise",null);E(this,"lastFetchError",null);E(this,"apiRequestService");if(!e||!e.customerId)throw new Error("[Kelviq SDK] KelviqClient: CustomerId is required in options.");this.options={...e,apiConfig:e.apiConfig||{},entitlementsPath:e.entitlementsPath||T},this.apiRequestService=i||C}async fetchAllEntitlements(e=!1){if(this.inFlightPromise&&!e)return this.inFlightPromise;if(this.entitlementsCache&&!e)return Promise.resolve(this.entitlementsCache);this.isFetching=!0,this.lastFetchError=null;const{apiUrl:i=this.options.environment==="sandbox"?D:L,entitlementsPath:t,customerId:c,accessToken:u,apiConfig:A,onError:r}=this.options,f=i.replace(/\/$/,""),l=t.replace(/^\//,""),m=`${f}/${l}`,R={customer_id:c};return this.inFlightPromise=this.apiRequestService({url:m,method:"GET",queryParams:R,accessToken:u,...A||{}}).then(n=>{if(n&&n.data&&Array.isArray(n.data.entitlements))return this.rawApiResponse=n.data,this.entitlementsCache=y(n.data),this.isFetching=!1,this.inFlightPromise=null,this.entitlementsCache;{const s=new Error("[Kelviq SDK] Received empty, malformed, or invalid data structure from entitlements API.");throw this.lastFetchError=s,this.isFetching=!1,this.inFlightPromise=null,this.entitlementsCache=null,this.rawApiResponse=null,r&&r(s),s}}).catch(n=>{const s=n instanceof Error?n:new Error(String(n));throw this.lastFetchError=s,this.isFetching=!1,this.inFlightPromise=null,this.entitlementsCache=null,this.rawApiResponse=null,r&&r(s),s}),this.inFlightPromise}getEntitlement(e){return this.entitlementsCache?this.entitlementsCache[e]??null:(console.warn(`[Kelviq SDK] getEntitlement: Entitlements not fetched or cache is empty for featureId '${e}'. Call fetchAllEntitlements() first.`),null)}getEntitlements(){return this.entitlementsCache}getRawEntitlement(e){return this.rawApiResponse?this.rawApiResponse.entitlements.filter(i=>i.featureId===e):(console.warn(`[Kelviq SDK] getRawEntitlement: Entitlements not fetched for featureId '${e}'. Call fetchAllEntitlements() first.`),null)}getRawEntitlements(){return this.rawApiResponse}hasAccess(e){if(!this.entitlementsCache)return console.warn(`[Kelviq SDK] hasAccess: Entitlements not fetched yet for featureId '${e}'. Call fetchAllEntitlements() first. Returning false.`),!1;const i=this.entitlementsCache[e];return i?i.hasAccess:!1}isLoading(){return this.isFetching}getLastError(){return this.lastFetchError}ready(){return this.readyPromise??Promise.resolve()}_setReadyPromise(e){this.readyPromise=e}clearCache(){this.entitlementsCache=null,this.rawApiResponse=null,this.isFetching=!1,this.lastFetchError=null,console.log("[Kelviq SDK] Entitlement cache cleared.")}}function U(a,e){const i={...a,initializeAndFetch:a.initializeAndFetch??!0,apiConfig:a.apiConfig||{},environment:a.environment||"production",entitlementsPath:a.entitlementsPath||T},t=new $(i,e);if(i.initializeAndFetch===!0){const c=t.fetchAllEntitlements().catch(u=>{console.error("[Kelviq SDK] Initial fetch on client creation failed:",u.message)});t._setReadyPromise(c.then(()=>{}))}return t}return U}();

package/dist/kelviq-js-sdk.js

@@ -1,257 +1,266 @@
-var K = Object.defineProperty;
-var C = (r, t, e) => t in r ? K(r, t, { enumerable: !0, configurable: !0, writable: !0, value: e }) : r[t] = e;
-var E = (r, t, e) => C(r, typeof t != "symbol" ? t + "" : t, e);
-function R(r) {
-  const t = {};
-  return !r || !Array.isArray(r.entitlements) ? (console.warn(
-    "[Kelviq SDK] transformApiEntitlements: Invalid or empty entitlements array in API response.",
-    r
-  ), t) : (r.entitlements.forEach((e) => {
-    if (!e || typeof e.featureId != "string" || typeof e.featureType != "string") {
+var S = Object.defineProperty;
+var T = (s, e, i) => e in s ? S(s, e, { enumerable: !0, configurable: !0, writable: !0, value: i }) : s[e] = i;
+var g = (s, e, i) => T(s, typeof e != "symbol" ? e + "" : e, i);
+function w(s) {
+  const e = {};
+  if (!s || !Array.isArray(s.entitlements))
+    return console.warn(
+      "[Kelviq SDK] transformApiEntitlements: Invalid or empty entitlements array in API response.",
+      s
+    ), e;
+  const i = {};
+  s.entitlements.forEach((t) => {
+    if (!t || typeof t.featureId != "string" || typeof t.featureType != "string") {
       console.warn(
         "[Kelviq SDK] transformApiEntitlements: Skipping invalid raw entitlement object:",
-        e
+        t
       );
       return;
     }
-    let n = null;
-    const m = {
-      featureId: e.featureId,
-      hasAccess: e.hasAccess
-    };
-    if (e.featureType === "BOOLEAN")
-      n = {
-        ...m,
-        type: "boolean"
-      };
-    else if (e.featureType === "CUSTOMIZABLE") {
-      const i = e;
-      n = {
-        ...m,
-        type: "customizable",
-        configuration: typeof i.value == "number" ? i.value : null
-      };
-    } else if (e.featureType === "METER") {
-      const i = e, p = typeof i.usageLimit == "number" ? i.usageLimit : null, o = typeof i.currentUsage == "number" ? i.currentUsage : 0;
-      n = {
-        ...m,
-        type: "metered",
-        limit: p,
-        used: o,
-        remaining: p !== null ? p - o : null,
-        resetAt: i.resetAt,
-        hardLimit: i.hardLimit
-      };
-    } else {
-      const i = e;
+    i[t.featureId] || (i[t.featureId] = []), i[t.featureId].push(t);
+  });
+  for (const t of Object.keys(i)) {
+    const c = i[t], u = c[0].featureType;
+    let E = 0, l = null, f = null, o = !1, m = !1;
+    if (u === "METER") {
+      let n = !0;
+      for (const r of c)
+        E += typeof r.currentUsage == "number" ? r.currentUsage : 0, typeof r.usageLimit == "number" && (l = (l ?? 0) + r.usageLimit, n = !1);
+      n && (l = null), f = l !== null ? l - E : null, o = c.some((r) => r.hardLimit === !0), m = f === null || f > 0;
+    } else if (u === "CUSTOMIZABLE") {
+      const n = c[0];
+      l = typeof n.usageLimit == "number" ? n.usageLimit : null, E = typeof n.currentUsage == "number" ? n.currentUsage : 0, f = typeof n.remaining == "number" ? n.remaining : null, o = n.hardLimit === !0, m = c.some((r) => r.hasAccess);
+    } else if (u === "BOOLEAN")
+      m = c.some((n) => n.hasAccess);
+    else {
       console.warn(
-        `[Kelviq SDK] transformApiEntitlements: Encountered unknown or unhandled entitlement featureType: '${String(i.featureType)}' for feature '${String(i.feature)}'. This entitlement will be ignored.`
+        `[Kelviq SDK] transformApiEntitlements: Encountered unknown featureType: '${u}' for feature '${t}'. This entitlement will be ignored.`
       );
+      continue;
     }
-    n && (t[n.featureId] = n);
-  }), t);
+    const A = {
+      featureId: t,
+      featureType: u,
+      hasAccess: m,
+      hardLimit: o,
+      currentUsage: E,
+      usageLimit: l,
+      remaining: f,
+      items: c
+    };
+    e[t] = A;
+  }
+  return e;
 }
-const $ = "GET", D = 5e3, F = 3, L = 1e3;
-function w(r) {
+const P = "GET", C = 5e3, K = 3, L = 1e3;
+function $(s) {
   const {
-    method: t = $,
-    headers: e = {},
+    method: e = P,
+    headers: i = {},
     // Renamed to avoid conflict with internal 'headers' variable
-    body: n,
-    timeout: m = D,
-    maxRetries: i = F,
-    backoffBaseDelay: p = L,
-    queryParams: o,
-    accessToken: g
+    body: t,
+    timeout: c = C,
+    maxRetries: u = K,
+    backoffBaseDelay: E = L,
+    queryParams: l,
+    accessToken: f
     // Use the direct accessToken
-  } = r;
-  let a = r.url, d = 0;
-  return new Promise((q, l) => {
-    if (o) {
-      const c = new URLSearchParams();
-      for (const f in o)
-        o[f] !== void 0 && c.append(f, String(o[f]));
-      c.toString() && (a = a + (a.includes("?") ? "&" : "?") + c.toString());
+  } = s;
+  let o = s.url, m = 0;
+  return new Promise((A, n) => {
+    if (l) {
+      const h = new URLSearchParams();
+      for (const d in l)
+        l[d] !== void 0 && h.append(d, String(l[d]));
+      h.toString() && (o = o + (o.includes("?") ? "&" : "?") + h.toString());
     }
-    function u() {
-      const c = new XMLHttpRequest();
-      c.open(t, a, !0), c.timeout = m;
-      const f = {
+    function r() {
+      const h = new XMLHttpRequest();
+      h.open(e, o, !0), h.timeout = c;
+      const d = {
         Accept: "application/json",
         "X-Requested-With": "XMLHttpRequest",
-        ...e
+        ...i
         // Apply custom headers, allowing them to override defaults
       };
-      t !== "GET" && n && typeof n == "object" && !(n instanceof FormData) && (f["Content-Type"] || (f["Content-Type"] = "application/json")), g && (f.Authorization = `Bearer ${g}`);
-      for (const [s, h] of Object.entries(f))
-        c.setRequestHeader(s, h);
-      c.onload = function() {
-        const { status: s, statusText: h, responseText: A } = c;
-        if (s >= 200 && s < 300)
+      e !== "GET" && t && typeof t == "object" && !(t instanceof FormData) && (d["Content-Type"] || (d["Content-Type"] = "application/json")), f && (d.Authorization = `Bearer ${f}`);
+      for (const [a, p] of Object.entries(d))
+        h.setRequestHeader(a, p);
+      h.onload = function() {
+        const { status: a, statusText: p, responseText: R } = h;
+        if (a >= 200 && a < 300)
           try {
-            const y = A ? JSON.parse(A) : {};
-            q({ status: s, statusText: h, data: y });
+            const y = R ? JSON.parse(R) : {};
+            A({ status: a, statusText: p, data: y });
           } catch (y) {
-            const S = y instanceof Error ? y : new Error(String(y));
+            const v = y instanceof Error ? y : new Error(String(y));
             console.error(
-              `Kelviq SDK (apiRequest): Invalid JSON response for URL ${a}. Error: ${S.message}. Response: ${A}`
-            ), l(new Error(`Invalid JSON response: ${S.message}`));
+              `Kelviq SDK (apiRequest): Invalid JSON response for URL ${o}. Error: ${v.message}. Response: ${R}`
+            ), n(new Error(`Invalid JSON response: ${v.message}`));
           }
         else
-          v(
-            `Request to ${a} failed with status ${s} ${h}. Response: ${A}`
+          q(
+            `Request to ${o} failed with status ${a} ${p}. Response: ${R}`
           );
-      }, c.onerror = () => v(
-        `Network error for URL ${a}. The request could not be completed.`
-      ), c.ontimeout = () => v(`Request to ${a} timed out.`);
-      function v(s) {
-        if (d < i) {
-          d++;
-          const h = Math.min(
-            p * Math.pow(2, d - 1),
+      }, h.onerror = () => q(
+        `Network error for URL ${o}. The request could not be completed.`
+      ), h.ontimeout = () => q(`Request to ${o} timed out.`);
+      function q(a) {
+        if (m < u) {
+          m++;
+          const p = Math.min(
+            E * Math.pow(2, m - 1),
             3e4
             // Cap retry delay at 30 seconds
           );
           console.warn(
-            `Kelviq SDK (apiRequest): Retrying request to ${a}. Attempt ${d}/${i}. Error: ${s}. Retrying in ${h}ms.`
-          ), setTimeout(u, h);
+            `Kelviq SDK (apiRequest): Retrying request to ${o}. Attempt ${m}/${u}. Error: ${a}. Retrying in ${p}ms.`
+          ), setTimeout(r, p);
         } else
-          l(
-            new Error(`${s} (Max retries ${i} reached)`)
+          n(
+            new Error(`${a} (Max retries ${u} reached)`)
           );
       }
       try {
-        let s = n;
-        n && typeof n == "object" && !(n instanceof FormData) && f["Content-Type"] === "application/json" && (s = JSON.stringify(n)), c.send(s);
-      } catch (s) {
-        const h = s instanceof Error ? s : new Error(String(s));
+        let a = t;
+        t && typeof t == "object" && !(t instanceof FormData) && d["Content-Type"] === "application/json" && (a = JSON.stringify(t)), h.send(a);
+      } catch (a) {
+        const p = a instanceof Error ? a : new Error(String(a));
         console.error(
-          `Kelviq SDK (apiRequest): Error sending request to ${a}.`,
-          h
-        ), l(new Error(`Failed to send request: ${h.message}`));
+          `Kelviq SDK (apiRequest): Error sending request to ${o}.`,
+          p
+        ), n(new Error(`Failed to send request: ${p.message}`));
       }
     }
-    u();
+    r();
   });
 }
-const I = "https://edge.api.kelviq.com/api/v1/", U = "https://edge.sandboxapi.kelviq.com/api/v1/", T = "entitlements/";
-class P {
+const D = "https://edge.api.kelviq.com/api/v1/", U = "https://edge.sandboxapi.kelviq.com/api/v1/", F = "entitlements/";
+class I {
   /**
    * Creates an instance of KelviqClient.
-   * Prefer using the `createKelviqClient` factory function for instantiation.
+   * Prefer using the `kelviqSDK` factory function for instantiation.
    * @internal
    * @param options Configuration options for the client.
    * @param customApiRequest Optional: A custom function to handle API requests, conforming to ApiRequestConfig and ApiResponse.
    */
-  constructor(t, e) {
-    E(this, "options");
-    E(this, "entitlementsCache", null);
-    E(this, "isFetching", !1);
-    E(this, "lastFetchError", null);
-    E(this, "apiRequestService");
-    if (!t || !t.customerId)
+  constructor(e, i) {
+    g(this, "options");
+    g(this, "entitlementsCache", null);
+    g(this, "rawApiResponse", null);
+    g(this, "isFetching", !1);
+    g(this, "inFlightPromise", null);
+    g(this, "readyPromise", null);
+    g(this, "lastFetchError", null);
+    g(this, "apiRequestService");
+    if (!e || !e.customerId)
       throw new Error(
         "[Kelviq SDK] KelviqClient: CustomerId is required in options."
       );
     this.options = {
-      ...t,
-      apiConfig: t.apiConfig || {},
-      entitlementsPath: t.entitlementsPath || T
-    }, this.apiRequestService = e || w;
+      ...e,
+      apiConfig: e.apiConfig || {},
+      entitlementsPath: e.entitlementsPath || F
+    }, this.apiRequestService = i || $;
   }
   /**
-   * Fetches all entitlements from the API for the configured orgId and customerId,
+   * Fetches all entitlements from the API for the configured customerId,
    * processes them, and caches the result.
    * Subsequent calls will return cached data unless `forceRefresh` is true.
    *
    * @param forceRefresh - If true, fetches from the API even if data is already cached. Defaults to false.
-   * @returns A promise that resolves to the map of entitlements (EntitlementMap).
+   * @returns A promise that resolves to the map of aggregated entitlements.
    * @throws Will throw an error if the API request fails after all retries.
    */
-  async fetchAllEntitlements(t = !1) {
-    if (this.isFetching)
-      return Promise.reject(
-        new Error("[Kelviq SDK] An entitlement fetch is already in progress.")
-      );
-    if (this.entitlementsCache && !t)
+  async fetchAllEntitlements(e = !1) {
+    if (this.inFlightPromise && !e)
+      return this.inFlightPromise;
+    if (this.entitlementsCache && !e)
       return Promise.resolve(this.entitlementsCache);
     this.isFetching = !0, this.lastFetchError = null;
     const {
-      apiUrl: e = this.options.environment === "sandbox" ? U : I,
-      entitlementsPath: n,
-      customerId: m,
-      accessToken: i,
-      apiConfig: p,
-      onError: o
-    } = this.options, g = e.replace(/\/$/, ""), a = n.replace(/^\//, ""), d = `${g}/${a}`, q = {
-      customer_id: m
+      apiUrl: i = this.options.environment === "sandbox" ? U : D,
+      entitlementsPath: t,
+      customerId: c,
+      accessToken: u,
+      apiConfig: E,
+      onError: l
+    } = this.options, f = i.replace(/\/$/, ""), o = t.replace(/^\//, ""), m = `${f}/${o}`, A = {
+      customer_id: c
     };
-    try {
-      const l = await this.apiRequestService(
-        {
-          url: d,
-          method: "GET",
-          queryParams: q,
-          accessToken: i,
-          ...p || {}
-        }
-      );
-      if (l && l.data && Array.isArray(l.data.entitlements))
-        return this.entitlementsCache = R(l.data), this.isFetching = !1, this.entitlementsCache;
+    return this.inFlightPromise = this.apiRequestService({
+      url: m,
+      method: "GET",
+      queryParams: A,
+      accessToken: u,
+      ...E || {}
+    }).then((n) => {
+      if (n && n.data && Array.isArray(n.data.entitlements))
+        return this.rawApiResponse = n.data, this.entitlementsCache = w(n.data), this.isFetching = !1, this.inFlightPromise = null, this.entitlementsCache;
       {
-        const u = new Error(
+        const r = new Error(
           "[Kelviq SDK] Received empty, malformed, or invalid data structure from entitlements API."
         );
-        throw this.lastFetchError = u, this.isFetching = !1, this.entitlementsCache = null, o && o(u), u;
+        throw this.lastFetchError = r, this.isFetching = !1, this.inFlightPromise = null, this.entitlementsCache = null, this.rawApiResponse = null, l && l(r), r;
       }
-    } catch (l) {
-      const u = l instanceof Error ? l : new Error(String(l));
-      throw this.lastFetchError = u, this.isFetching = !1, this.entitlementsCache = null, o && o(u), u;
-    }
+    }).catch((n) => {
+      const r = n instanceof Error ? n : new Error(String(n));
+      throw this.lastFetchError = r, this.isFetching = !1, this.inFlightPromise = null, this.entitlementsCache = null, this.rawApiResponse = null, l && l(r), r;
+    }), this.inFlightPromise;
   }
   /**
-   * Retrieves a specific entitlement from the local cache.
-   * Note: `fetchAllEntitlements()` must be called successfully at least once before using this method,
-   * or the cache will be empty.
+   * Retrieves a specific aggregated entitlement from the local cache.
    *
-   * @param featureId The unique key of the feature.
-   * @param type The expected type of the entitlement ('boolean', 'config', 'metered').
-   * @returns The processed entitlement object if found in the cache and the type matches, otherwise `null`.
-   * Logs a warning if entitlements haven't been fetched or if a type mismatch occurs.
+   * @param featureId The unique identifier of the feature.
+   * @returns The aggregated Entitlement object if found, otherwise `null`.
    */
-  getEntitlement(t, e) {
-    if (!this.entitlementsCache)
-      return console.warn(
-        `[Kelviq SDK] getEntitlement: Entitlements not fetched or cache is empty for featureId '${t}'. Call fetchAllEntitlements() first.`
-      ), null;
-    const n = this.entitlementsCache[t];
-    return n ? n.type === e ? n : (console.warn(
-      `[Kelviq SDK] getEntitlement: Type mismatch for featureId '${t}'. Expected type '${e}', but cached type is '${n.type}'.`
-    ), null) : null;
+  getEntitlement(e) {
+    return this.entitlementsCache ? this.entitlementsCache[e] ?? null : (console.warn(
+      `[Kelviq SDK] getEntitlement: Entitlements not fetched or cache is empty for featureId '${e}'. Call fetchAllEntitlements() first.`
+    ), null);
+  }
+  /**
+   * Returns all aggregated entitlements as a map keyed by featureId.
+   *
+   * @returns Record of featureId to aggregated Entitlement, or `null` if not fetched.
+   */
+  getEntitlements() {
+    return this.entitlementsCache;
+  }
+  /**
+   * Returns the raw API items for a specific featureId (un-aggregated).
+   *
+   * @param featureId The unique identifier of the feature.
+   * @returns Array of raw entitlement items for the given featureId, or `null` if not fetched.
+   */
+  getRawEntitlement(e) {
+    return this.rawApiResponse ? this.rawApiResponse.entitlements.filter(
+      (i) => i.featureId === e
+    ) : (console.warn(
+      `[Kelviq SDK] getRawEntitlement: Entitlements not fetched for featureId '${e}'. Call fetchAllEntitlements() first.`
+    ), null);
+  }
+  /**
+   * Returns the full raw API response including the customer_id wrapper.
+   *
+   * @returns The raw API response `{ customer_id, entitlements }`, or `null` if not fetched.
+   */
+  getRawEntitlements() {
+    return this.rawApiResponse;
   }
   /**
    * Checks if the user has access to a specific feature based on cached entitlements.
-   * Note: `fetchAllEntitlements()` should be called successfully at least once before using this method.
    *
-   * @param featureId The key of the feature.
-   * @returns `true` if access is granted, `false` if denied or the feature is not found in the cache.
-   * Logs a warning and returns `false` if entitlements haven't been fetched.
+   * @param featureId The identifier of the feature.
+   * @returns `true` if access is granted, `false` otherwise.
    */
-  hasAccess(t) {
+  hasAccess(e) {
     if (!this.entitlementsCache)
       return console.warn(
-        `[Kelviq SDK] hasAccess: Entitlements not fetched yet for featureId '${t}'. Call fetchAllEntitlements() first. Returning false.`
+        `[Kelviq SDK] hasAccess: Entitlements not fetched yet for featureId '${e}'. Call fetchAllEntitlements() first. Returning false.`
       ), !1;
-    const e = this.entitlementsCache[t];
-    return e ? e.hasAccess : !1;
-  }
-  /**
-   * Returns the currently cached map of all entitlements.
-   * `fetchAllEntitlements()` should be called successfully at least once.
-   * @returns The EntitlementMap (a record of featureKey to entitlement data) or `null` if not fetched or an error occurred during the last fetch.
-   */
-  getAllEntitlements() {
-    return this.entitlementsCache;
+    const i = this.entitlementsCache[e];
+    return i ? i.hasAccess : !1;
   }
   /**
    * Indicates if an entitlement fetch operation is currently in progress.
@@ -267,29 +276,46 @@ class P {
   getLastError() {
     return this.lastFetchError;
   }
+  /**
+   * Returns a promise that resolves when the initial fetch (triggered by `initializeAndFetch: true`) completes.
+   * If no initial fetch was triggered, resolves immediately.
+   */
+  ready() {
+    return this.readyPromise ?? Promise.resolve();
+  }
+  /**
+   * @internal Sets the ready promise. Called by the factory when initializeAndFetch is true.
+   */
+  _setReadyPromise(e) {
+    this.readyPromise = e;
+  }
   /**
    * Clears the local entitlement cache and resets loading and error states.
-   * After calling this, `fetchAllEntitlements()` will need to be called again to populate the cache.
    */
   clearCache() {
-    this.entitlementsCache = null, this.isFetching = !1, this.lastFetchError = null, console.log("[Kelviq SDK] Entitlement cache cleared.");
+    this.entitlementsCache = null, this.rawApiResponse = null, this.isFetching = !1, this.lastFetchError = null, console.log("[Kelviq SDK] Entitlement cache cleared.");
   }
 }
-function _(r, t) {
-  const e = {
-    ...r,
-    initializeAndFetch: r.initializeAndFetch || !0,
-    apiConfig: r.apiConfig || {},
-    environment: r.environment || "production",
-    entitlementsPath: r.entitlementsPath || T
-  }, n = new P(e, t);
-  return e.initializeAndFetch === !0 && n.fetchAllEntitlements().catch((m) => {
-    console.error(
-      "[Kelviq SDK] Initial fetch on client creation failed:",
-      m.message
-    );
-  }), n;
+function b(s, e) {
+  const i = {
+    ...s,
+    initializeAndFetch: s.initializeAndFetch ?? !0,
+    apiConfig: s.apiConfig || {},
+    environment: s.environment || "production",
+    entitlementsPath: s.entitlementsPath || F
+  }, t = new I(i, e);
+  if (i.initializeAndFetch === !0) {
+    const c = t.fetchAllEntitlements().catch((u) => {
+      console.error(
+        "[Kelviq SDK] Initial fetch on client creation failed:",
+        u.message
+      );
+    });
+    t._setReadyPromise(c.then(() => {
+    }));
+  }
+  return t;
 }
 export {
-  _ as default
+  b as default
 };

package/dist/kelviq-js-sdk.umd.js

@@ -1 +1 @@
-(function(f,o){typeof exports=="object"&&typeof module<"u"?module.exports=o():typeof define=="function"&&define.amd?define(o):(f=typeof globalThis<"u"?globalThis:f||self,f.kelviqSDK=o())})(this,function(){"use strict";var b=Object.defineProperty;var P=(f,o,y)=>o in f?b(f,o,{enumerable:!0,configurable:!0,writable:!0,value:y}):f[o]=y;var A=(f,o,y)=>P(f,typeof o!="symbol"?o+"":o,y);function f(s){const n={};return!s||!Array.isArray(s.entitlements)?(console.warn("[Kelviq SDK] transformApiEntitlements: Invalid or empty entitlements array in API response.",s),n):(s.entitlements.forEach(e=>{if(!e||typeof e.featureId!="string"||typeof e.featureType!="string"){console.warn("[Kelviq SDK] transformApiEntitlements: Skipping invalid raw entitlement object:",e);return}let t=null;const d={featureId:e.featureId,hasAccess:e.hasAccess};if(e.featureType==="BOOLEAN")t={...d,type:"boolean"};else if(e.featureType==="CUSTOMIZABLE"){const i=e;t={...d,type:"customizable",configuration:typeof i.value=="number"?i.value:null}}else if(e.featureType==="METER"){const i=e,E=typeof i.usageLimit=="number"?i.usageLimit:null,l=typeof i.currentUsage=="number"?i.currentUsage:0;t={...d,type:"metered",limit:E,used:l,remaining:E!==null?E-l:null,resetAt:i.resetAt,hardLimit:i.hardLimit}}else{const i=e;console.warn(`[Kelviq SDK] transformApiEntitlements: Encountered unknown or unhandled entitlement featureType: '${String(i.featureType)}' for feature '${String(i.feature)}'. This entitlement will be ignored.`)}t&&(n[t.featureId]=t)}),n)}const o="GET",y=5e3,R=3,$=1e3;function F(s){const{method:n=o,headers:e={},body:t,timeout:d=y,maxRetries:i=R,backoffBaseDelay:E=$,queryParams:l,accessToken:T}=s;let a=s.url,g=0;return new Promise((S,c)=>{if(l){const u=new URLSearchParams;for(const p in l)l[p]!==void 0&&u.append(p,String(l[p]));u.toString()&&(a=a+(a.includes("?")?"&":"?")+u.toString())}function h(){const u=new XMLHttpRequest;u.open(n,a,!0),u.timeout=d;const p={Accept:"application/json","X-Requested-With":"XMLHttpRequest",...e};n!=="GET"&&t&&typeof t=="object"&&!(t instanceof FormData)&&(p["Content-Type"]||(p["Content-Type"]="application/json")),T&&(p.Authorization=`Bearer ${T}`);for(const[r,m]of Object.entries(p))u.setRequestHeader(r,m);u.onload=function(){const{status:r,statusText:m,responseText:v}=u;if(r>=200&&r<300)try{const q=v?JSON.parse(v):{};S({status:r,statusText:m,data:q})}catch(q){const D=q instanceof Error?q:new Error(String(q));console.error(`Kelviq SDK (apiRequest): Invalid JSON response for URL ${a}. Error: ${D.message}. Response: ${v}`),c(new Error(`Invalid JSON response: ${D.message}`))}else K(`Request to ${a} failed with status ${r} ${m}. Response: ${v}`)},u.onerror=()=>K(`Network error for URL ${a}. The request could not be completed.`),u.ontimeout=()=>K(`Request to ${a} timed out.`);function K(r){if(g<i){g++;const m=Math.min(E*Math.pow(2,g-1),3e4);console.warn(`Kelviq SDK (apiRequest): Retrying request to ${a}. Attempt ${g}/${i}. Error: ${r}. Retrying in ${m}ms.`),setTimeout(h,m)}else c(new Error(`${r} (Max retries ${i} reached)`))}try{let r=t;t&&typeof t=="object"&&!(t instanceof FormData)&&p["Content-Type"]==="application/json"&&(r=JSON.stringify(t)),u.send(r)}catch(r){const m=r instanceof Error?r:new Error(String(r));console.error(`Kelviq SDK (apiRequest): Error sending request to ${a}.`,m),c(new Error(`Failed to send request: ${m.message}`))}}h()})}const L="https://edge.api.kelviq.com/api/v1/",w="https://edge.sandboxapi.kelviq.com/api/v1/",C="entitlements/";class I{constructor(n,e){A(this,"options");A(this,"entitlementsCache",null);A(this,"isFetching",!1);A(this,"lastFetchError",null);A(this,"apiRequestService");if(!n||!n.customerId)throw new Error("[Kelviq SDK] KelviqClient: CustomerId is required in options.");this.options={...n,apiConfig:n.apiConfig||{},entitlementsPath:n.entitlementsPath||C},this.apiRequestService=e||F}async fetchAllEntitlements(n=!1){if(this.isFetching)return Promise.reject(new Error("[Kelviq SDK] An entitlement fetch is already in progress."));if(this.entitlementsCache&&!n)return Promise.resolve(this.entitlementsCache);this.isFetching=!0,this.lastFetchError=null;const{apiUrl:e=this.options.environment==="sandbox"?w:L,entitlementsPath:t,customerId:d,accessToken:i,apiConfig:E,onError:l}=this.options,T=e.replace(/\/$/,""),a=t.replace(/^\//,""),g=`${T}/${a}`,S={customer_id:d};try{const c=await this.apiRequestService({url:g,method:"GET",queryParams:S,accessToken:i,...E||{}});if(c&&c.data&&Array.isArray(c.data.entitlements))return this.entitlementsCache=f(c.data),this.isFetching=!1,this.entitlementsCache;{const h=new Error("[Kelviq SDK] Received empty, malformed, or invalid data structure from entitlements API.");throw this.lastFetchError=h,this.isFetching=!1,this.entitlementsCache=null,l&&l(h),h}}catch(c){const h=c instanceof Error?c:new Error(String(c));throw this.lastFetchError=h,this.isFetching=!1,this.entitlementsCache=null,l&&l(h),h}}getEntitlement(n,e){if(!this.entitlementsCache)return console.warn(`[Kelviq SDK] getEntitlement: Entitlements not fetched or cache is empty for featureId '${n}'. Call fetchAllEntitlements() first.`),null;const t=this.entitlementsCache[n];return t?t.type===e?t:(console.warn(`[Kelviq SDK] getEntitlement: Type mismatch for featureId '${n}'. Expected type '${e}', but cached type is '${t.type}'.`),null):null}hasAccess(n){if(!this.entitlementsCache)return console.warn(`[Kelviq SDK] hasAccess: Entitlements not fetched yet for featureId '${n}'. Call fetchAllEntitlements() first. Returning false.`),!1;const e=this.entitlementsCache[n];return e?e.hasAccess:!1}getAllEntitlements(){return this.entitlementsCache}isLoading(){return this.isFetching}getLastError(){return this.lastFetchError}clearCache(){this.entitlementsCache=null,this.isFetching=!1,this.lastFetchError=null,console.log("[Kelviq SDK] Entitlement cache cleared.")}}function U(s,n){const e={...s,initializeAndFetch:s.initializeAndFetch||!0,apiConfig:s.apiConfig||{},environment:s.environment||"production",entitlementsPath:s.entitlementsPath||C},t=new I(e,n);return e.initializeAndFetch===!0&&t.fetchAllEntitlements().catch(d=>{console.error("[Kelviq SDK] Initial fetch on client creation failed:",d.message)}),t}return U});
+(function(f,c){typeof exports=="object"&&typeof module<"u"?module.exports=c():typeof define=="function"&&define.amd?define(c):(f=typeof globalThis<"u"?globalThis:f||self,f.kelviqSDK=c())})(this,function(){"use strict";var I=Object.defineProperty;var b=(f,c,q)=>c in f?I(f,c,{enumerable:!0,configurable:!0,writable:!0,value:q}):f[c]=q;var A=(f,c,q)=>b(f,typeof c!="symbol"?c+"":c,q);function f(a){const e={};if(!a||!Array.isArray(a.entitlements))return console.warn("[Kelviq SDK] transformApiEntitlements: Invalid or empty entitlements array in API response.",a),e;const i={};a.entitlements.forEach(t=>{if(!t||typeof t.featureId!="string"||typeof t.featureType!="string"){console.warn("[Kelviq SDK] transformApiEntitlements: Skipping invalid raw entitlement object:",t);return}i[t.featureId]||(i[t.featureId]=[]),i[t.featureId].push(t)});for(const t of Object.keys(i)){const u=i[t],h=u[0].featureType;let y=0,r=null,p=null,o=!1,d=!1;if(h==="METER"){let n=!0;for(const s of u)y+=typeof s.currentUsage=="number"?s.currentUsage:0,typeof s.usageLimit=="number"&&(r=(r??0)+s.usageLimit,n=!1);n&&(r=null),p=r!==null?r-y:null,o=u.some(s=>s.hardLimit===!0),d=p===null||p>0}else if(h==="CUSTOMIZABLE"){const n=u[0];r=typeof n.usageLimit=="number"?n.usageLimit:null,y=typeof n.currentUsage=="number"?n.currentUsage:0,p=typeof n.remaining=="number"?n.remaining:null,o=n.hardLimit===!0,d=u.some(s=>s.hasAccess)}else if(h==="BOOLEAN")d=u.some(n=>n.hasAccess);else{console.warn(`[Kelviq SDK] transformApiEntitlements: Encountered unknown featureType: '${h}' for feature '${t}'. This entitlement will be ignored.`);continue}const R={featureId:t,featureType:h,hasAccess:d,hardLimit:o,currentUsage:y,usageLimit:r,remaining:p,items:u};e[t]=R}return e}const c="GET",q=5e3,K=3,P=1e3;function C(a){const{method:e=c,headers:i={},body:t,timeout:u=q,maxRetries:h=K,backoffBaseDelay:y=P,queryParams:r,accessToken:p}=a;let o=a.url,d=0;return new Promise((R,n)=>{if(r){const m=new URLSearchParams;for(const E in r)r[E]!==void 0&&m.append(E,String(r[E]));m.toString()&&(o=o+(o.includes("?")?"&":"?")+m.toString())}function s(){const m=new XMLHttpRequest;m.open(e,o,!0),m.timeout=u;const E={Accept:"application/json","X-Requested-With":"XMLHttpRequest",...i};e!=="GET"&&t&&typeof t=="object"&&!(t instanceof FormData)&&(E["Content-Type"]||(E["Content-Type"]="application/json")),p&&(E.Authorization=`Bearer ${p}`);for(const[l,g]of Object.entries(E))m.setRequestHeader(l,g);m.onload=function(){const{status:l,statusText:g,responseText:T}=m;if(l>=200&&l<300)try{const v=T?JSON.parse(T):{};R({status:l,statusText:g,data:v})}catch(v){const w=v instanceof Error?v:new Error(String(v));console.error(`Kelviq SDK (apiRequest): Invalid JSON response for URL ${o}. Error: ${w.message}. Response: ${T}`),n(new Error(`Invalid JSON response: ${w.message}`))}else F(`Request to ${o} failed with status ${l} ${g}. Response: ${T}`)},m.onerror=()=>F(`Network error for URL ${o}. The request could not be completed.`),m.ontimeout=()=>F(`Request to ${o} timed out.`);function F(l){if(d<h){d++;const g=Math.min(y*Math.pow(2,d-1),3e4);console.warn(`Kelviq SDK (apiRequest): Retrying request to ${o}. Attempt ${d}/${h}. Error: ${l}. Retrying in ${g}ms.`),setTimeout(s,g)}else n(new Error(`${l} (Max retries ${h} reached)`))}try{let l=t;t&&typeof t=="object"&&!(t instanceof FormData)&&E["Content-Type"]==="application/json"&&(l=JSON.stringify(t)),m.send(l)}catch(l){const g=l instanceof Error?l:new Error(String(l));console.error(`Kelviq SDK (apiRequest): Error sending request to ${o}.`,g),n(new Error(`Failed to send request: ${g.message}`))}}s()})}const L="https://edge.api.kelviq.com/api/v1/",D="https://edge.sandboxapi.kelviq.com/api/v1/",S="entitlements/";class ${constructor(e,i){A(this,"options");A(this,"entitlementsCache",null);A(this,"rawApiResponse",null);A(this,"isFetching",!1);A(this,"inFlightPromise",null);A(this,"readyPromise",null);A(this,"lastFetchError",null);A(this,"apiRequestService");if(!e||!e.customerId)throw new Error("[Kelviq SDK] KelviqClient: CustomerId is required in options.");this.options={...e,apiConfig:e.apiConfig||{},entitlementsPath:e.entitlementsPath||S},this.apiRequestService=i||C}async fetchAllEntitlements(e=!1){if(this.inFlightPromise&&!e)return this.inFlightPromise;if(this.entitlementsCache&&!e)return Promise.resolve(this.entitlementsCache);this.isFetching=!0,this.lastFetchError=null;const{apiUrl:i=this.options.environment==="sandbox"?D:L,entitlementsPath:t,customerId:u,accessToken:h,apiConfig:y,onError:r}=this.options,p=i.replace(/\/$/,""),o=t.replace(/^\//,""),d=`${p}/${o}`,R={customer_id:u};return this.inFlightPromise=this.apiRequestService({url:d,method:"GET",queryParams:R,accessToken:h,...y||{}}).then(n=>{if(n&&n.data&&Array.isArray(n.data.entitlements))return this.rawApiResponse=n.data,this.entitlementsCache=f(n.data),this.isFetching=!1,this.inFlightPromise=null,this.entitlementsCache;{const s=new Error("[Kelviq SDK] Received empty, malformed, or invalid data structure from entitlements API.");throw this.lastFetchError=s,this.isFetching=!1,this.inFlightPromise=null,this.entitlementsCache=null,this.rawApiResponse=null,r&&r(s),s}}).catch(n=>{const s=n instanceof Error?n:new Error(String(n));throw this.lastFetchError=s,this.isFetching=!1,this.inFlightPromise=null,this.entitlementsCache=null,this.rawApiResponse=null,r&&r(s),s}),this.inFlightPromise}getEntitlement(e){return this.entitlementsCache?this.entitlementsCache[e]??null:(console.warn(`[Kelviq SDK] getEntitlement: Entitlements not fetched or cache is empty for featureId '${e}'. Call fetchAllEntitlements() first.`),null)}getEntitlements(){return this.entitlementsCache}getRawEntitlement(e){return this.rawApiResponse?this.rawApiResponse.entitlements.filter(i=>i.featureId===e):(console.warn(`[Kelviq SDK] getRawEntitlement: Entitlements not fetched for featureId '${e}'. Call fetchAllEntitlements() first.`),null)}getRawEntitlements(){return this.rawApiResponse}hasAccess(e){if(!this.entitlementsCache)return console.warn(`[Kelviq SDK] hasAccess: Entitlements not fetched yet for featureId '${e}'. Call fetchAllEntitlements() first. Returning false.`),!1;const i=this.entitlementsCache[e];return i?i.hasAccess:!1}isLoading(){return this.isFetching}getLastError(){return this.lastFetchError}ready(){return this.readyPromise??Promise.resolve()}_setReadyPromise(e){this.readyPromise=e}clearCache(){this.entitlementsCache=null,this.rawApiResponse=null,this.isFetching=!1,this.lastFetchError=null,console.log("[Kelviq SDK] Entitlement cache cleared.")}}function U(a,e){const i={...a,initializeAndFetch:a.initializeAndFetch??!0,apiConfig:a.apiConfig||{},environment:a.environment||"production",entitlementsPath:a.entitlementsPath||S},t=new $(i,e);if(i.initializeAndFetch===!0){const u=t.fetchAllEntitlements().catch(h=>{console.error("[Kelviq SDK] Initial fetch on client creation failed:",h.message)});t._setReadyPromise(u.then(()=>{}))}return t}return U});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kelviq/js-sdk",
-  "version": "1.0.0",
+  "version": "2.0.0-beta",
   "module": "./dist/kelviq-js-sdk.js",
   "type": "module",
   "files": [
@@ -30,7 +30,9 @@
     "format:styles": "stylelint ./**/*.{css,scss} --fix",
     "format": "npm run format:scripts && npm run format:styles",
     "prepare": "husky && echo 'npx lint-staged' > .husky/pre-commit && git add .husky/pre-commit",
-    "uninstall-husky": "npm uninstall husky --no-save && git config --unset core.hooksPath && npx rimraf .husky"
+    "uninstall-husky": "npm uninstall husky --no-save && git config --unset core.hooksPath && npx rimraf .husky",
+    "publish:stable": "./publish.sh",
+    "publish:beta": "./publish.sh beta"
   },
   "devDependencies": {
     "@types/jsdom": "^21.1.7",