@kelviq/react-sdk 0.0.1-beta

package/README.md

@@ -0,0 +1,377 @@
+
+The `@kelviq/react-sdk` provides a seamless way to integrate Kelviq entitlement management into your React applications.
+
+## Overview
+
+- A **React Context Provider** (`KelviqProvider`) to initialize and configure the SDK.
+- **Hooks** to easily access entitlement status and data within your components.
+- **Conditional rendering components** to show or hide UI elements based on feature access.
+- Automatic and manual **data fetching** and caching mechanisms.
+
+The SDK fetches all entitlements for a given organization and customer, caches them, and makes them available throughout your application via React Context and custom hooks.
+
+## **2. Installation**
+
+Install the SDK using npm or yarn:
+
+``` bash
+npm install @kelviq/react-sdk
+# or
+yarn add @kelviq/react-sdk
+
+```
+
+You will also need `react` as a peer dependency.
+
+## **3. Setup & Configuration**
+
+### `KelviqProvider`
+
+The core of the SDK is the `KelviqProvider`. You need to wrap your application (or the relevant part of it) with this provider. It initializes the SDK and makes entitlement data available to its children components via context.
+
+``` tsx
+// In your App.tsx or main application entry point
+import React from 'react';
+import { KelviqProvider, PDPaywall } from '@kelviq/react-sdk';
+
+const App = () => {
+  return (
+    <KelviqProvider
+      customerId="your-customer-id"
+      accessToken="your-access-token"
+    >
+      <MyAppContent />
+    </KelviqProvider>
+  );
+};
+
+const MyAppContent = () => {
+
+  return (
+    <PDPaywall offeringId="your-offering-id">
+      <div>My Application</div>
+    </PDPaywall>
+  );
+
+};
+
+export default App;
+
+```
+
+### Required Props for `KelviqProvider`
+
+- `customerId: string`
+  - The ID of the customer for whom entitlements are being fetched. This will be sent as a query parameter (`customer_id`).
+- `accessToken: string | null`
+  - Your static API token or Bearer token for authenticating requests to the Kelviq API. If provided, it will be included in the `Authorization: Bearer <accessToken>` header.
+
+### Optional Props for `KelviqProvider`
+
+  
+- `apiUrl: string`
+  - The base URL for your Kelviq API. For example, `https://edge.api.kelviq.com/api/v1`.
+- `entitlementsPath: string`
+  - The specific path for the endpoint that returns all entitlements for a customer. This path will be appended to `apiUrl`. For example, `entitlement-check` or `user-entitlements`.
+- `config?: KelviqApiBehaviorOptions`
+  - An optional object to configure more advanced behaviors of the SDK.
+
+### **Configuration Object (**`config: KelviqApiBehaviorOptions`**)**
+
+This optional object can contain the following properties:
+
+- `onError?: (error: Error) => void`
+  - A callback function that will be invoked if an error occurs during the API request for entitlements.
+- `maxRetries?: number`
+  - The maximum number of times to retry a failed API request. Defaults to the value set in your `apiRequest` service (typically 3).
+- `timeout?: number`
+  - Timeout for API requests in milliseconds. Defaults to the value set in your `apiRequest` service (typically 5000ms).
+- `backoffBaseDelay?: number`
+  - Base delay (in milliseconds) for the exponential backoff strategy used in retries. Defaults to the value set in your `apiRequest` service (typically 1000ms).
+- `fetchEntitlementsOnMount?: boolean`
+  - Defaults to `true`. If true, entitlements are fetched automatically when the `KelviqProvider` mounts.
+  - Set to `false` if you want to control the initial fetch manually using the `refreshAllEntitlements` function from the `useKelviq` hook.
+
+
+## **4. Fetching Entitlements**
+
+### **Automatic Fetching on Mount**
+
+By default (`fetchEntitlementsOnMount: true` in the `config` prop, or if `config` or this specific option is omitted), the SDK will attempt to fetch all entitlements for the specified `customerId` as soon as the `KelviqProvider` is mounted.
+
+The `isLoading` state from `useKelviq()` will be `true` during this initial fetch.
+
+### **Manual Fetching**
+
+If `fetchEntitlementsOnMount` is set to `false`, or if you need to re-fetch entitlements at any point (e.g., after a user action that might change their entitlements), you can use the `refreshAllEntitlements` function.
+
+
+``` tsx
+import { useKelviq } from '@kelviq/react-sdk';
+
+function MyComponent() {
+  const { refreshAllEntitlements, isLoading, error } = useKelviq();
+
+  const handleRefresh = async () => {
+    try {
+      await refreshAllEntitlements();
+      console.log("Entitlements refreshed!");
+    } catch (e) {
+      console.error("Failed to refresh entitlements:", e);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handleRefresh} disabled={isLoading}>
+        {isLoading ? 'Refreshing...' : 'Refresh Entitlements'}
+      </button>
+      {error && <p style={{ color: 'red' }}>Error: {error.message}</p>}
+      {/* ... rest of your component ... */}
+    </div>
+  );
+}
+
+```
+
+## **5. Accessing Entitlement Data (Hooks)**
+
+The SDK provides several hooks to access entitlement data and SDK state.
+
+### `useKelviq()`
+
+This is the primary hook to access the SDK's context.
+
+- **Returns:** `KelviqContextValue` object containing:
+  - `allEntitlements: AsyncState<EntitlementMap | null>`: The state object for all fetched entitlements.
+    - `data`: An `EntitlementMap` (a `Record<string, AnyEntitlement>`) where keys are `featureKey`s, or `null` if not loaded or error.
+    - `isLoading`: Boolean indicating if the `allEntitlements` data is currently being fetched/refreshed.
+    - `error`: An `Error` object if the last fetch failed, otherwise `null`.
+  - `refreshAllEntitlements: () => Promise<void>`: Function to manually trigger a re-fetch of all entitlements.
+  - `getEntitlement: <T extends AnyEntitlement>(featureKey: string, type: T['type']) => AsyncState<T | null>`: Function to get a specific entitlement's state from the cache.
+  - `hasAccess: (featureKey: string) => boolean | undefined`: A utility function to quickly check access for a feature. Returns `true` if access is granted, `false` if denied or feature not found, and `undefined` if data is loading or an error occurred.
+  - `isLoading: boolean`: A global loading state indicating if the SDK is performing its initial configured fetch or a refresh operation.
+  - `error: Error | null`: A global error state reflecting any error from the last fetch operation initiated by the provider.
+  - `customerId: string`: The customer ID passed to the provider.
+  - `apiUrl: string`: The base API URL passed to the provider.
+  - `entitlementsPath: string`: The entitlements path passed to the provider.
+
+### `useAllEntitlements()`
+
+A convenience hook that directly returns the `allEntitlements` state object.
+
+- **Returns:** `AsyncState<EntitlementMap | null>`
+
+``` tsx
+import { useAllEntitlements } from '@kelviq/react-sdk';
+
+function EntitlementsList() {
+  const { data: entitlementsMap, isLoading, error } = useAllEntitlements();
+
+  if (isLoading) return <p>Loading all entitlements...</p>;
+  if (error) return <p>Error loading entitlements: {error.message}</p>;
+  if (!entitlementsMap) return <p>No entitlements data.</p>;
+
+  return (
+    <ul>
+      {Object.values(entitlementsMap).map(ent => (
+        <li key={ent.featureKey}>
+          {ent.featureKey}: {ent.hasAccess ? 'Enabled' : 'Disabled'} ({ent.type})
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+```
+
+### `useBooleanEntitlement(featureKey: string)`
+
+Fetches the state for a specific boolean entitlement from the cache.
+
+- **Arguments:**
+  - `featureKey: string`: The key of the boolean feature.
+- **Returns:** `AsyncState<BooleanEntitlement | null>`
+
+### `useConfigEntitlement(featureKey: string)`
+
+Fetches the state for a specific configuration entitlement from the cache.
+
+- **Arguments:**
+  - `featureKey: string`: The key of the configuration feature.
+- **Returns:** `AsyncState<ConfigEntitlement | null>` (where `ConfigEntitlement` has a `configuration: number | null` property).
+
+### `useMeteredEntitlement(featureKey: string)`
+
+Fetches the state for a specific metered entitlement from the cache.
+
+- **Arguments:**
+  - `featureKey: string`: The key of the metered feature.
+- **Returns:** `AsyncState<MeteredEntitlement | null>`
+
+**Example using a specific entitlement hook:**
+
+``` tsx
+import { useBooleanEntitlement } from '@kelviq/react-sdk';
+
+function FeatureSpecificComponent({ featureKey }: { featureKey: string }) {
+  const { data: entitlement, isLoading, error } = useBooleanEntitlement(featureKey);
+
+  if (isLoading) return <p>Loading feature {featureKey}...</p>;
+  if (error) return <p>Error loading feature {featureKey}: {error.message}</p>;
+
+  if (entitlement && entitlement.hasAccess) {
+    return <p>You have access to {featureKey}!</p>;
+  } else {
+    return <p>You do not have access to {featureKey}.</p>;
+  }
+}
+
+```
+
+## **6. Conditional Rendering Components**
+
+These components provide a declarative way to render UI based on entitlement status. They internally use the respective hooks.
+
+**Common Props:**
+
+- `featureKey: string`: The unique key of the feature to check.
+- `children: ReactNode | ((data: E) => ReactNode)`:
+  - If a `ReactNode`, it's rendered when the user is entitled and conditions are met.
+  - If a function (render prop), it's called with the entitlement data (`BooleanEntitlement`, `ConfigEntitlement`, or `MeteredEntitlement`) and its return value is rendered.
+- `fallback?: ReactNode`: Content to render if the user is not entitled, or if data is loading (and no `loadingComponent` is provided), or if an error occurs. Defaults to `null`.
+- `loadingComponent?: ReactNode`: Specific content to render while the entitlement data is loading. Overrides `fallback` during loading.
+
+### `ShowWhenBooleanEntitled`
+
+Renders children if the boolean feature is enabled (`hasAccess: true`).
+
+``` tsx
+import { ShowWhenBooleanEntitled } from '@kelviq/react-sdk';
+
+<ShowWhenBooleanEntitled
+  featureKey="enable-dark-mode"
+  loadingComponent={<p>Checking theme settings...</p>}
+  fallback={<p>Dark mode is not available.</p>}
+>
+  <button>Toggle Dark Mode</button>
+</ShowWhenBooleanEntitled>
+
+<ShowWhenBooleanEntitled featureKey="show-advanced-settings">
+  {(entitlementData) => (
+    <div>Advanced settings for {entitlementData.featureKey} are visible!</div>
+  )}
+</ShowWhenBooleanEntitled>
+
+```
+
+### `ShowWhenConfigEntitled`
+
+Renders children if the config feature is enabled and provides the numeric configuration value to the children render prop.
+
+- **Children Prop:** `(config: number) => ReactNode` (Required to be a function for this component).
+
+``` tsx
+import { ShowWhenConfigEntitled } from '@kelviq/react-sdk';
+
+<ShowWhenConfigEntitled
+  featureKey="max-items-per-page"
+  loadingComponent={<p>Loading display settings...</p>}
+  fallback={<p>Default item limit applies.</p>}
+>
+  {(maxItems) => <p>You can display up to {maxItems} items per page.</p>}
+</ShowWhenConfigEntitled>
+
+```
+
+### `ShowWhenMeteredEntitled`
+
+Renders children if the metered feature is enabled and, by default, if `remaining` usage is greater than 0 or unlimited (`limit` is `null`).
+
+- **Optional Prop:**
+  - `condition?: (data: MeteredEntitlement) => boolean`: A custom function to further determine if children should render based on the metered entitlement data.
+- **Children Prop:** Can be `ReactNode` or `(data: MeteredEntitlement) => ReactNode`.
+
+``` tsx
+import { ShowWhenMeteredEntitled } from '@kelviq/react-sdk';
+
+<ShowWhenMeteredEntitled
+  featureKey="api-calls-quota"
+  loadingComponent={<p>Loading API quota...</p>}
+  fallback={<p>API call limit reached or feature not available.</p>}
+>
+  {(meterData) => (
+    <div>
+      <p>API Calls Used: {meterData.used} / {meterData.limit === null ? 'Unlimited' : meterData.limit}</p>
+      <p>Remaining: {meterData.remaining === null ? 'Unlimited' : meterData.remaining}</p>
+    </div>
+  )}
+</ShowWhenMeteredEntitled>
+
+```
+
+## **7. Key Types**
+
+The SDK exports several types for better integration with TypeScript. Some key ones include:
+
+- `KelviqProviderOptions`: Configuration for the provider.
+- `KelviqContextValue`: The shape of the object returned by `useKelviq()`.
+- `AsyncState<T>`: Generic type for asynchronous data states.
+- `EntitlementMap`: The structure of the cached entitlements (`Record<string, AnyEntitlement>`).
+- `Entitlement`, `BooleanEntitlement`, `ConfigEntitlement`, `MeteredEntitlement`: Processed entitlement types.
+- `ApiRequestConfig`, `ApiResponse`: Interfaces related to the underlying `apiRequest` service.
+- `RawEntitlementsApiResponse` and related `Raw...` types: Represent the structure of the direct API response.
+
+You can import these types from `@kelviq/react-sdk/types` (assuming your `src/types/index.ts` re-exports them) or directly from the main SDK entry if configured.
+
+## **8. Error Handling**
+
+- **Provider Level:** The `onError` callback in `KelviqProviderOptions` can be used to globally handle errors that occur during the entitlement fetching process initiated by the provider.
+- **Hook Level:** Each hook (`useAllEntitlements`, `useBooleanEntitlement`, etc.) returns an `AsyncState` object which includes an `error: Error | null` property. You can check this to handle errors specific to that data slice.
+- **Context Level:** `useKelviq()` also returns a global `error: Error | null` state, reflecting errors from the provider's most recent fetch operation.
+
+## **9. Example Usage**
+
+A comprehensive example is provided within the comments of the SDK code, demonstrating provider setup and component usage. The core setup involves:
+
+1. Wrapping your application with `KelviqProvider` and providing the required props (`customerId`, `accessToken`)
+2. Using hooks like `useBooleanEntitlement` or conditional components like `ShowWhenBooleanEntitled` in your components to control UI and behavior based on entitlements.
+
+## **10. API Request Service**
+
+The SDK relies on an `apiRequest` function for making HTTP requests. The SDK's `KelviqProvider` passes configuration like `timeout`, `maxRetries`, `backoffBaseDelay`, and `accessToken` to this function.
+
+- **Your Responsibility:** You need to ensure that your project includes an implementation of this `apiRequest` service (e.g., in `src/services/makeRequest.service.ts`) that matches the `ApiRequestConfig` and `ApiResponse` interfaces used by the SDK. This service should handle actual HTTP communication, including appending query parameters passed via `ApiRequestConfig.queryParams` and using the `accessToken` to set the `Authorization` header.
+- The placeholder `apiRequest` function included in the SDK's source code is for demonstration and type-checking purposes only and will not make real API calls.
+
+## **11. Project Structure (for contributors/reference)**
+
+The SDK source code (`src/`) is organized as follows:
+
+- `components/`: Contains conditional rendering React components.
+  - `ShowWhenBooleanEntitled.tsx`
+  - `ShowWhenConfigEntitled.tsx`
+  - `ShowWhenMeteredEntitled.tsx`
+  - `ShowWhenEntitledInternal.tsx` (Internal helper, not typically exported)
+  - `index.ts` (Exports public components)
+- `context/`: Defines the React Context.
+  - `KelviqContext.ts`
+- `hooks/`: Contains all custom React Hooks.
+  - `useKelviq.ts`
+  - `useAllEntitlements.ts`
+  - `useBooleanEntitlement.ts`
+  - `useConfigEntitlement.ts`
+  - `useMeteredEntitlement.ts`
+  - `index.ts` (Exports all hooks)
+- `provider/`: Contains the main `KelviqProvider`.
+  - `KelviqProvider.tsx`
+- `types/`: Contains all TypeScript definitions.
+  - `api.types.ts` (Raw types from API)
+  - `sdk.types.ts` (Processed types for SDK and public use)
+  - `index.ts` (Re-exports all types)
+- `utils/`: Contains utility functions.
+  - `transformations.ts` (For `transformApiEntitlements`)
+  - `index.ts` (Exports utilities)
+- `index.ts`: The main entry point of the SDK, re-exporting all public APIs (provider, hooks, components, types).
+
+This documentation should provide a good starting point for developers using your `@kelviq/react-sdk`. Remember to replace placeholder URLs and token examples with relevant information for your users.

package/dist/components/ShowWhenBooleanEntitled.d.ts

@@ -0,0 +1,3 @@
+import { BooleanEntitlement } from '../types/sdk.types';
+import { ShowWhenEntitledProps } from './ShowWhenEntitledInternal';
+export declare const ShowWhenBooleanEntitled: React.FC<Omit<ShowWhenEntitledProps<BooleanEntitlement>, 'condition' | 'type'>>;

package/dist/components/ShowWhenConfigEntitled.d.ts

@@ -0,0 +1,14 @@
+import { ReactNode } from 'react';
+import { ConfigEntitlement } from '../types/sdk.types';
+import { ShowWhenEntitledProps } from './ShowWhenEntitledInternal';
+/**
+ * Conditionally renders children based on a configuration entitlement.
+ * The children prop is a render function that receives the numeric configuration value.
+ * @param featureKey The key of the configuration feature.
+ * @param children A function that receives the numeric configuration and returns a ReactNode.
+ * @param fallback Content to render if not entitled, loading (and no loadingComponent), error, or config is not a number.
+ * @param loadingComponent Specific content to render while the entitlement is loading.
+ */
+export declare const ShowWhenConfigEntitled: React.FC<Omit<ShowWhenEntitledProps<ConfigEntitlement>, 'condition' | 'type' | 'children'> & {
+    children: (config: number) => ReactNode;
+}>;

package/dist/components/ShowWhenEntitledInternal.d.ts

@@ -0,0 +1,12 @@
+import { ReactNode } from 'react';
+import { AnyEntitlement } from '../types/sdk.types';
+export interface ShowWhenEntitledProps<E extends AnyEntitlement> {
+    featureKey: string;
+    children: ReactNode | ((data: E) => ReactNode);
+    fallback?: ReactNode;
+    loadingComponent?: ReactNode;
+    condition?: (data: E) => boolean;
+}
+export declare const ShowWhenEntitledInternal: <E extends AnyEntitlement>({ featureKey, type, children, fallback, loadingComponent, condition, }: ShowWhenEntitledProps<E> & {
+    type: E["type"];
+}) => JSX.Element;

package/dist/components/ShowWhenMeteredEntitled.d.ts

@@ -0,0 +1,13 @@
+import { MeteredEntitlement } from '../types/sdk.types';
+import { ShowWhenEntitledProps } from './ShowWhenEntitledInternal';
+/**
+ * Conditionally renders children based on a metered entitlement.
+ * By default, children are rendered if hasAccess is true and remaining usage is greater than 0 or unlimited.
+ * A custom `condition` function can be provided.
+ * @param featureKey The key of the metered feature.
+ * @param children Content to render if entitled and condition is met. Can be a ReactNode or a render function receiving the entitlement data.
+ * @param fallback Content to render if not entitled, loading (and no loadingComponent), error, or condition not met.
+ * @param loadingComponent Specific content to render while the entitlement is loading.
+ * @param condition Optional function to further refine when children are rendered based on metered data.
+ */
+export declare const ShowWhenMeteredEntitled: React.FC<Omit<ShowWhenEntitledProps<MeteredEntitlement>, 'type'>>;

package/dist/contexts/KelviqContext.d.ts

@@ -0,0 +1,17 @@
+import { EntitlementMap, AnyEntitlement } from '../types/sdk.types';
+import { AsyncState } from '../types';
+/** Defines the shape of the context value provided by KelviqProvider. */
+export interface KelviqContextValue {
+    allEntitlements: AsyncState<EntitlementMap | null>;
+    refreshAllEntitlements: () => Promise<void>;
+    getEntitlement: <T extends AnyEntitlement>(featureKey: string, type: T['type']) => AsyncState<T | null>;
+    hasAccess: (featureKey: string) => boolean | undefined;
+    isLoading: boolean;
+    error: Error | null;
+    customerId: string;
+    environment: string;
+    apiUrl: string;
+    entitlementsPath: string;
+}
+export declare const defaultKelviqContextValue: KelviqContextValue;
+export declare const KelviqContext: import('react').Context<KelviqContextValue>;

package/dist/contexts/KelviqProvider.d.ts

@@ -0,0 +1,18 @@
+import { default as React, ReactNode } from 'react';
+import { KelviqApiBehaviorOptions } from '../types/sdk.types';
+interface KelviqProviderProps {
+    children: ReactNode;
+    /** Base URL for the Kelviq API (e.g., https://edge.stagingapi.kelviq.com/api/v1). Required. */
+    apiUrl?: string;
+    /** Path for fetching all entitlements (e.g., "/entitlements"). Required. */
+    entitlementsPath?: string;
+    /** The customer ID. Required. */
+    customerId: string;
+    environment?: 'production' | 'sandbox';
+    /** Optional: The static authentication token string for API requests. */
+    accessToken: string | null;
+    /** Optional: Further configuration options for API behavior. */
+    config?: KelviqApiBehaviorOptions;
+}
+export declare const KelviqProvider: React.FC<KelviqProviderProps>;
+export {};

package/dist/hooks/index.d.ts

@@ -0,0 +1,5 @@
+export * from './useKelviq';
+export * from './useAllEntitlements';
+export * from './useBooleanEntitlement';
+export * from './useConfigEntitlement';
+export * from './useMeteredEntitlement';

package/dist/hooks/useAllEntitlements.d.ts

@@ -0,0 +1,7 @@
+import { AsyncState } from '../types';
+import { EntitlementMap } from '../types/sdk.types';
+/**
+ * Hook to get the state of all fetched and processed entitlements.
+ * @returns AsyncState containing the map of all entitlements (EntitlementMap) or null.
+ */
+export declare const useAllEntitlements: () => AsyncState<EntitlementMap | null>;

package/dist/hooks/useBooleanEntitlement.d.ts

@@ -0,0 +1,8 @@
+import { AsyncState } from '../types';
+import { BooleanEntitlement } from '../types/sdk.types';
+/**
+ * Hook to get a specific boolean entitlement's state.
+ * @param featureKey The key of the boolean feature.
+ * @returns AsyncState containing the BooleanEntitlement or null if not found/error.
+ */
+export declare const useBooleanEntitlement: (featureKey: string) => AsyncState<BooleanEntitlement | null>;

package/dist/hooks/useConfigEntitlement.d.ts

@@ -0,0 +1,8 @@
+import { AsyncState } from '../types';
+import { ConfigEntitlement } from '../types/sdk.types';
+/**
+ * Hook to get a specific configuration entitlement's state.
+ * @param featureKey The key of the configuration feature.
+ * @returns AsyncState containing the ConfigEntitlement (with numeric configuration) or null.
+ */
+export declare const useConfigEntitlement: (featureKey: string) => AsyncState<ConfigEntitlement | null>;

package/dist/hooks/useKelviq.d.ts

@@ -0,0 +1,7 @@
+import { KelviqContextValue } from '../contexts/KelviqContext';
+/**
+ * Custom hook to access the Kelviq context.
+ * Provides access to entitlement data, loading states, and refresh functions.
+ * Throws an error if used outside of a KelviqProvider.
+ */
+export declare const useKelviq: () => KelviqContextValue;

package/dist/hooks/useMeteredEntitlement.d.ts

@@ -0,0 +1,8 @@
+import { AsyncState } from '../types';
+import { MeteredEntitlement } from '../types/sdk.types';
+/**
+ * Hook to get a specific metered entitlement's state.
+ * @param featureKey The key of the metered feature.
+ * @returns AsyncState containing the MeteredEntitlement or null.
+ */
+export declare const useMeteredEntitlement: (featureKey: string) => AsyncState<MeteredEntitlement | null>;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from './contexts/KelviqProvider';
+export type * from './types';
+export * from './components/ShowWhenConfigEntitled';
+export * from './components/ShowWhenMeteredEntitled';
+export * from './components/ShowWhenBooleanEntitled';
+export * from './contexts/KelviqContext';
+export * from './hooks/useKelviq';
+export * from './hooks/useAllEntitlements';
+export * from './hooks/useBooleanEntitlement';
+export * from './hooks/useConfigEntitlement';
+export * from './hooks/useMeteredEntitlement';

package/dist/kelviq-react-sdk.js

@@ -0,0 +1,461 @@
+import { jsx as q, Fragment as b } from "react/jsx-runtime";
+import { createContext as C, useState as U, useCallback as R, useEffect as _, useMemo as F, useContext as O } from "react";
+const B = "GET", j = 5e3, N = 3, z = 1e3;
+function G(e) {
+  const {
+    method: i = B,
+    headers: t = {},
+    // Renamed to avoid conflict with internal 'headers' variable
+    body: n,
+    timeout: v = j,
+    maxRetries: o = N,
+    backoffBaseDelay: y = z,
+    queryParams: p,
+    accessToken: w
+    // Use the direct accessToken
+  } = e;
+  let { url: f } = e, c = 0;
+  return new Promise((T, m) => {
+    if (p) {
+      const s = new URLSearchParams();
+      for (const h in p)
+        p[h] !== void 0 && s.append(h, String(p[h]));
+      s.toString() && (f += (f.includes("?") ? "&" : "?") + s.toString());
+    }
+    function a() {
+      const s = new XMLHttpRequest();
+      s.open(i, f, !0), s.timeout = v;
+      const h = {
+        Accept: "application/json",
+        "X-Requested-With": "XMLHttpRequest",
+        ...t
+        // Apply custom headers, allowing them to override defaults
+      };
+      i !== "GET" && n && typeof n == "object" && !(n instanceof FormData) && (h["Content-Type"] || (h["Content-Type"] = "application/json")), w && (h.Authorization = `Bearer ${w}`);
+      for (const [l, E] of Object.entries(h))
+        s.setRequestHeader(l, E);
+      s.onload = function() {
+        const { status: l, statusText: E, responseText: A } = s;
+        if (l >= 200 && l < 300)
+          try {
+            const S = A ? JSON.parse(A) : {};
+            T({ status: l, statusText: E, data: S });
+          } catch (S) {
+            const $ = S instanceof Error ? S : new Error(String(S));
+            console.error(
+              `Kelviq SDK (apiRequest): Invalid JSON response for URL ${f}. Error: ${$.message}. Response: ${A}`
+            ), m(
+              new Error(
+                `Invalid JSON response: ${$.message}`
+              )
+            );
+          }
+        else
+          L(
+            `Request to ${f} failed with status ${l} ${E}. Response: ${A}`
+          );
+      }, s.onerror = () => L(
+        `Network error for URL ${f}. The request could not be completed.`
+      ), s.ontimeout = () => L(`Request to ${f} timed out.`);
+      function L(l) {
+        if (c < o) {
+          c++;
+          const E = Math.min(
+            y * Math.pow(2, c - 1),
+            3e4
+            // Cap retry delay at 30 seconds
+          );
+          console.warn(
+            `Kelviq SDK (apiRequest): Retrying request to ${f}. Attempt ${c}/${o}. Error: ${l}. Retrying in ${E}ms.`
+          ), setTimeout(a, E);
+        } else
+          m(
+            new Error(
+              `${l} (Max retries ${o} reached)`
+            )
+          );
+      }
+      try {
+        let l = n;
+        n && typeof n == "object" && !(n instanceof FormData) && h["Content-Type"] === "application/json" && (l = JSON.stringify(n)), s.send(l);
+      } catch (l) {
+        const E = l instanceof Error ? l : new Error(String(l));
+        console.error(
+          `Kelviq SDK (apiRequest): Error sending request to ${f}.`,
+          E
+        ), m(new Error(`Failed to send request: ${E.message}`));
+      }
+    }
+    a();
+  });
+}
+function H(e) {
+  const i = {};
+  return !e || !Array.isArray(e.entitlements) ? (console.warn(
+    "Kelviq SDK: Invalid or empty entitlements array in API response.",
+    e
+  ), i) : (e.entitlements.forEach((t) => {
+    if (!t || typeof t.featureId != "string" || typeof t.featureType != "string") {
+      console.warn(
+        "Kelviq SDK: Skipping invalid raw entitlement object:",
+        t
+      );
+      return;
+    }
+    let n = null;
+    const v = {
+      // Omit type as it's added in switch
+      featureKey: t.featureId,
+      hasAccess: t.hasAccess
+    };
+    switch (t.featureType) {
+      case "BOOLEAN":
+        n = {
+          ...v,
+          type: "boolean"
+        };
+        break;
+      case "CUSTOMIZABLE": {
+        const o = t;
+        n = {
+          ...v,
+          type: "customizable",
+          configuration: typeof o.value == "number" ? o.value : null
+        };
+        break;
+      }
+      case "METER": {
+        const o = t, y = typeof o.usageLimit == "number" ? o.usageLimit : null, p = typeof o.currentUsage == "number" ? o.currentUsage : 0;
+        n = {
+          ...v,
+          type: "metered",
+          limit: y,
+          used: p,
+          remaining: y !== null ? y - p : null,
+          // If limit is null (unlimited), remaining is also null
+          resetAt: o.resetAt,
+          hardLimit: o.hardLimit
+        };
+        break;
+      }
+      default: {
+        const o = t;
+        console.warn(
+          `Kelviq SDK: Encountered unknown or unhandled entitlement featureType: '${String(
+            o.featureType
+          )}' for feature '${String(
+            o.featureId
+          )}'. This entitlement will be ignored.`
+        );
+        break;
+      }
+    }
+    n && (i[n.featureKey] = n);
+  }), i);
+}
+const W = () => ({
+  data: null,
+  isLoading: !1,
+  error: new Error(
+    "KelviqContext not fully initialized or entitlements not fetched."
+  )
+}), I = {
+  allEntitlements: {
+    data: null,
+    isLoading: !0,
+    error: null
+  },
+  refreshAllEntitlements: () => (console.warn(
+    "refreshAllEntitlements called on default KelviqContext. Ensure KelviqProvider is properly set up."
+  ), Promise.resolve()),
+  getEntitlement: W,
+  hasAccess: () => {
+  },
+  isLoading: !0,
+  error: null,
+  apiUrl: "",
+  environment: "production",
+  entitlementsPath: "",
+  customerId: ""
+}, M = C(
+  I
+), X = "https://edge.api.kelviq.com/api/v1/", J = "https://edge.sandboxapi.kelviq.com/api/v1/", V = "entitlements/", Q = ({
+  children: e,
+  apiUrl: i,
+  // Direct prop
+  entitlementsPath: t = V,
+  // Direct prop
+  customerId: n,
+  // Direct prop
+  environment: v = "production",
+  accessToken: o,
+  // Direct prop
+  config: y = {}
+  // Optional config object with defaults
+}) => {
+  const {
+    onError: p,
+    maxRetries: w,
+    timeout: f,
+    backoffBaseDelay: c,
+    fetchEntitlementsOnMount: T = !0
+    // Default within config
+  } = y, m = i || (v === "sandbox" ? J : X), [a, s] = U({
+    data: null,
+    isLoading: !!m && T,
+    // Only loading if apiBaseUrl is present and fetchOnMount is true
+    error: null
+  }), [h, L] = U(
+    !!m && T
+  ), [l, E] = U(null), A = R(
+    (g, d, r) => {
+      const u = new Error(
+        `Kelviq SDK (${d}): ${g}`
+      );
+      console.error(u.message, r || ""), E((P) => P || u), p && p(u);
+    },
+    [p]
+  ), S = R(() => {
+    if (!m) {
+      const r = "API URL not configured. Cannot fetch entitlements.";
+      return s({
+        data: null,
+        isLoading: !1,
+        error: new Error(r)
+      }), A(r, "fetchAllEntitlements"), L(!1), Promise.reject(new Error(r));
+    }
+    if (!n) {
+      const r = "CustomerId must be provided as props to KelviqProvider.";
+      return s(() => ({
+        data: null,
+        isLoading: !1,
+        error: new Error(r)
+      })), A(r, "fetchAllEntitlements"), L(!1), Promise.reject(new Error(r));
+    }
+    s((r) => ({
+      ...r,
+      isLoading: !0,
+      error: null
+    })), L(!0), E(null);
+    const g = `${m.replace(/\/$/, "")}/${t.replace(/^\//, "")}`;
+    return G({
+      url: g,
+      method: "GET",
+      timeout: f,
+      maxRetries: w,
+      backoffBaseDelay: c,
+      // Pass this to apiRequest
+      accessToken: o,
+      queryParams: {
+        customer_id: n
+      }
+    }).then((r) => {
+      if (r && r.data && Array.isArray(r.data.entitlements)) {
+        const u = H(
+          r.data
+        );
+        s({
+          data: u,
+          isLoading: !1,
+          error: null
+        });
+      } else {
+        const u = new Error(
+          "Received empty, malformed, or invalid data structure from entitlements API."
+        );
+        throw s({
+          data: null,
+          isLoading: !1,
+          error: u
+        }), A(
+          u.message,
+          "fetchAllEntitlements",
+          r
+        ), u;
+      }
+    }).catch((r) => {
+      const u = r instanceof Error ? r : new Error(String(r));
+      return s((P) => ({
+        ...P,
+        isLoading: !1,
+        error: u
+      })), A(u.message, "fetchAllEntitlements", r), Promise.reject(u);
+    }).finally(() => {
+      L(!1);
+    });
+  }, [
+    m,
+    n,
+    t,
+    f,
+    w,
+    c,
+    o,
+    A
+  ]);
+  _(() => {
+    let g = !0;
+    if (!m) {
+      if (g) {
+        const d = new Error(
+          "KelviqProvider: `apiBaseUrl` must be provided in config."
+        );
+        E(d), L(!1), s((r) => ({
+          ...r,
+          isLoading: !1,
+          error: d
+        })), y.onError && y.onError(d);
+      }
+      return;
+    }
+    return T ? S().catch((d) => {
+      g && h && L(!1), console.error(
+        "Kelviq SDK: Initial entitlement fetch failed.",
+        d
+      );
+    }) : g && (s((d) => ({
+      ...d,
+      isLoading: !1,
+      data: null,
+      error: null
+    })), L(!1)), () => {
+      g = !1;
+    };
+  }, [m, T, y.onError]);
+  const $ = R(
+    (g, d) => {
+      if (a.isLoading)
+        return { data: null, isLoading: !0, error: null };
+      if (a.error && !a.data)
+        return {
+          data: null,
+          isLoading: !1,
+          error: a.error
+        };
+      if (a.data) {
+        const u = a.data[g];
+        return u ? u.type === d ? {
+          data: u,
+          isLoading: !1,
+          error: null
+        } : {
+          data: null,
+          isLoading: !1,
+          error: new Error(
+            `Entitlement type mismatch for ${g}. Expected ${d}, got ${u.type}`
+          )
+        } : { data: null, isLoading: !1, error: null };
+      }
+      const r = m ? `Entitlements not yet fetched for ${g}. Call refreshAllEntitlements or ensure fetchEntitlementsOnMount is true.` : "API URL not configured. Check KelviqProvider configuration.";
+      return {
+        data: null,
+        isLoading: !1,
+        error: new Error(r)
+      };
+    },
+    [a, m]
+  ), D = R(
+    (g) => {
+      if (a.isLoading && !a.data || a.error && !a.data || !a.data) return;
+      const d = a.data[g];
+      return d ? d.hasAccess : !1;
+    },
+    [a]
+  ), x = F(
+    () => ({
+      allEntitlements: a,
+      refreshAllEntitlements: S,
+      getEntitlement: $,
+      hasAccess: D,
+      isLoading: h,
+      error: l,
+      environment: v,
+      apiUrl: m,
+      entitlementsPath: t,
+      customerId: n
+    }),
+    [
+      a,
+      S,
+      $,
+      D,
+      h,
+      l,
+      v,
+      m,
+      t,
+      n
+    ]
+  );
+  return /* @__PURE__ */ q(M.Provider, { value: x, children: e });
+}, K = () => {
+  const e = O(M);
+  if (e === void 0 || e === I)
+    throw new Error(
+      "useKelviq must be used within an initialized KelviqProvider."
+    );
+  return e;
+}, k = ({
+  featureKey: e,
+  type: i,
+  children: t,
+  fallback: n = null,
+  loadingComponent: v,
+  condition: o
+}) => {
+  const {
+    getEntitlement: y,
+    isLoading: p,
+    error: w,
+    allEntitlements: f
+  } = K(), c = y(e, i);
+  return c.isLoading || p && !c.data && !c.error && !f.data && !f.error ? /* @__PURE__ */ q(b, { children: v !== void 0 ? v : n }) : c.error || w && !c.data ? /* @__PURE__ */ q(b, { children: n }) : !c.data || !c.data.hasAccess || o && !o(c.data) ? /* @__PURE__ */ q(b, { children: n }) : typeof t == "function" ? /* @__PURE__ */ q(b, { children: t(c.data) }) : /* @__PURE__ */ q(b, { children: t });
+}, ee = ({ children: e, ...i }) => /* @__PURE__ */ q(
+  k,
+  {
+    ...i,
+    type: "customizable",
+    children: (t) => t.hasAccess && t.configuration !== null && typeof t.configuration == "number" ? e(t.configuration) : /* @__PURE__ */ q(b, { children: i.fallback || null })
+  }
+), te = (e) => {
+  const i = (t) => t.hasAccess && (t.remaining === null || t.remaining > 0);
+  return /* @__PURE__ */ q(
+    k,
+    {
+      ...e,
+      type: "metered",
+      condition: e.condition || i
+    }
+  );
+}, re = (e) => /* @__PURE__ */ q(
+  k,
+  {
+    ...e,
+    type: "boolean"
+  }
+), ne = () => {
+  const { allEntitlements: e } = K();
+  return e;
+}, oe = (e) => {
+  const { getEntitlement: i } = K();
+  return i(e, "boolean");
+}, ie = (e) => {
+  const { getEntitlement: i } = K();
+  return i(e, "customizable");
+}, se = (e) => {
+  const { getEntitlement: i } = K();
+  return i(e, "metered");
+};
+export {
+  M as KelviqContext,
+  Q as KelviqProvider,
+  re as ShowWhenBooleanEntitled,
+  ee as ShowWhenConfigEntitled,
+  te as ShowWhenMeteredEntitled,
+  I as defaultKelviqContextValue,
+  ne as useAllEntitlements,
+  oe as useBooleanEntitlement,
+  ie as useConfigEntitlement,
+  K as useKelviq,
+  se as useMeteredEntitlement
+};

package/dist/kelviq-react-sdk.umd.cjs

@@ -0,0 +1 @@
+(function(c,l){typeof exports=="object"&&typeof module<"u"?l(exports,require("react/jsx-runtime"),require("react")):typeof define=="function"&&define.amd?define(["exports","react/jsx-runtime","react"],l):(c=typeof globalThis<"u"?globalThis:c||self,l(c.KelviqReactSDK={},c.jsxRuntime,c.React))})(this,function(c,l,q){"use strict";const P="GET";function I(e){const{method:i=P,headers:t={},body:r,timeout:y=5e3,maxRetries:o=3,backoffBaseDelay:L=1e3,queryParams:v,accessToken:K}=e;let{url:E}=e,f=0;return new Promise((b,g)=>{if(v){const s=new URLSearchParams;for(const A in v)v[A]!==void 0&&s.append(A,String(v[A]));s.toString()&&(E+=(E.includes("?")?"&":"?")+s.toString())}function a(){const s=new XMLHttpRequest;s.open(i,E,!0),s.timeout=y;const A={Accept:"application/json","X-Requested-With":"XMLHttpRequest",...t};i!=="GET"&&r&&typeof r=="object"&&!(r instanceof FormData)&&(A["Content-Type"]||(A["Content-Type"]="application/json")),K&&(A.Authorization=`Bearer ${K}`);for(const[u,h]of Object.entries(A))s.setRequestHeader(u,h);s.onload=function(){const{status:u,statusText:h,responseText:T}=s;if(u>=200&&u<300)try{const w=T?JSON.parse(T):{};b({status:u,statusText:h,data:w})}catch(w){const C=w instanceof Error?w:new Error(String(w));console.error(`Kelviq SDK (apiRequest): Invalid JSON response for URL ${E}. Error: ${C.message}. Response: ${T}`),g(new Error(`Invalid JSON response: ${C.message}`))}else S(`Request to ${E} failed with status ${u} ${h}. Response: ${T}`)},s.onerror=()=>S(`Network error for URL ${E}. The request could not be completed.`),s.ontimeout=()=>S(`Request to ${E} timed out.`);function S(u){if(f<o){f++;const h=Math.min(L*Math.pow(2,f-1),3e4);console.warn(`Kelviq SDK (apiRequest): Retrying request to ${E}. Attempt ${f}/${o}. Error: ${u}. Retrying in ${h}ms.`),setTimeout(a,h)}else g(new Error(`${u} (Max retries ${o} reached)`))}try{let u=r;r&&typeof r=="object"&&!(r instanceof FormData)&&A["Content-Type"]==="application/json"&&(u=JSON.stringify(r)),s.send(u)}catch(u){const h=u instanceof Error?u:new Error(String(u));console.error(`Kelviq SDK (apiRequest): Error sending request to ${E}.`,h),g(new Error(`Failed to send request: ${h.message}`))}}a()})}function _(e){const i={};return!e||!Array.isArray(e.entitlements)?(console.warn("Kelviq SDK: Invalid or empty entitlements array in API response.",e),i):(e.entitlements.forEach(t=>{if(!t||typeof t.featureId!="string"||typeof t.featureType!="string"){console.warn("Kelviq SDK: Skipping invalid raw entitlement object:",t);return}let r=null;const y={featureKey:t.featureId,hasAccess:t.hasAccess};switch(t.featureType){case"BOOLEAN":r={...y,type:"boolean"};break;case"CUSTOMIZABLE":{const o=t;r={...y,type:"customizable",configuration:typeof o.value=="number"?o.value:null};break}case"METER":{const o=t,L=typeof o.usageLimit=="number"?o.usageLimit:null,v=typeof o.currentUsage=="number"?o.currentUsage:0;r={...y,type:"metered",limit:L,used:v,remaining:L!==null?L-v:null,resetAt:o.resetAt,hardLimit:o.hardLimit};break}default:{const o=t;console.warn(`Kelviq SDK: Encountered unknown or unhandled entitlement featureType: '${String(o.featureType)}' for feature '${String(o.featureId)}'. This entitlement will be ignored.`);break}}r&&(i[r.featureKey]=r)}),i)}const D={allEntitlements:{data:null,isLoading:!0,error:null},refreshAllEntitlements:()=>(console.warn("refreshAllEntitlements called on default KelviqContext. Ensure KelviqProvider is properly set up."),Promise.resolve()),getEntitlement:()=>({data:null,isLoading:!1,error:new Error("KelviqContext not fully initialized or entitlements not fetched.")}),hasAccess:()=>{},isLoading:!0,error:null,apiUrl:"",environment:"production",entitlementsPath:"",customerId:""},U=q.createContext(D),R="https://edge.api.kelviq.com/api/v1/",O="https://edge.sandboxapi.kelviq.com/api/v1/",B="entitlements/",x=({children:e,apiUrl:i,entitlementsPath:t=B,customerId:r,environment:y="production",accessToken:o,config:L={}})=>{const{onError:v,maxRetries:K,timeout:E,backoffBaseDelay:f,fetchEntitlementsOnMount:b=!0}=L,g=i||(y==="sandbox"?O:R),[a,s]=q.useState({data:null,isLoading:!!g&&b,error:null}),[A,S]=q.useState(!!g&&b),[u,h]=q.useState(null),T=q.useCallback((p,m,n)=>{const d=new Error(`Kelviq SDK (${m}): ${p}`);console.error(d.message,n||""),h(k=>k||d),v&&v(d)},[v]),w=q.useCallback(()=>{if(!g){const n="API URL not configured. Cannot fetch entitlements.";return s({data:null,isLoading:!1,error:new Error(n)}),T(n,"fetchAllEntitlements"),S(!1),Promise.reject(new Error(n))}if(!r){const n="CustomerId must be provided as props to KelviqProvider.";return s(()=>({data:null,isLoading:!1,error:new Error(n)})),T(n,"fetchAllEntitlements"),S(!1),Promise.reject(new Error(n))}s(n=>({...n,isLoading:!0,error:null})),S(!0),h(null);const p=`${g.replace(/\/$/,"")}/${t.replace(/^\//,"")}`;return I({url:p,method:"GET",timeout:E,maxRetries:K,backoffBaseDelay:f,accessToken:o,queryParams:{customer_id:r}}).then(n=>{if(n&&n.data&&Array.isArray(n.data.entitlements)){const d=_(n.data);s({data:d,isLoading:!1,error:null})}else{const d=new Error("Received empty, malformed, or invalid data structure from entitlements API.");throw s({data:null,isLoading:!1,error:d}),T(d.message,"fetchAllEntitlements",n),d}}).catch(n=>{const d=n instanceof Error?n:new Error(String(n));return s(k=>({...k,isLoading:!1,error:d})),T(d.message,"fetchAllEntitlements",n),Promise.reject(d)}).finally(()=>{S(!1)})},[g,r,t,E,K,f,o,T]);q.useEffect(()=>{let p=!0;if(!g){if(p){const m=new Error("KelviqProvider: `apiBaseUrl` must be provided in config.");h(m),S(!1),s(n=>({...n,isLoading:!1,error:m})),L.onError&&L.onError(m)}return}return b?w().catch(m=>{p&&A&&S(!1),console.error("Kelviq SDK: Initial entitlement fetch failed.",m)}):p&&(s(m=>({...m,isLoading:!1,data:null,error:null})),S(!1)),()=>{p=!1}},[g,b,L.onError]);const C=q.useCallback((p,m)=>{if(a.isLoading)return{data:null,isLoading:!0,error:null};if(a.error&&!a.data)return{data:null,isLoading:!1,error:a.error};if(a.data){const d=a.data[p];return d?d.type===m?{data:d,isLoading:!1,error:null}:{data:null,isLoading:!1,error:new Error(`Entitlement type mismatch for ${p}. Expected ${m}, got ${d.type}`)}:{data:null,isLoading:!1,error:null}}const n=g?`Entitlements not yet fetched for ${p}. Call refreshAllEntitlements or ensure fetchEntitlementsOnMount is true.`:"API URL not configured. Check KelviqProvider configuration.";return{data:null,isLoading:!1,error:new Error(n)}},[a,g]),F=q.useCallback(p=>{if(a.isLoading&&!a.data||a.error&&!a.data||!a.data)return;const m=a.data[p];return m?m.hasAccess:!1},[a]),J=q.useMemo(()=>({allEntitlements:a,refreshAllEntitlements:w,getEntitlement:C,hasAccess:F,isLoading:A,error:u,environment:y,apiUrl:g,entitlementsPath:t,customerId:r}),[a,w,C,F,A,u,y,g,t,r]);return l.jsx(U.Provider,{value:J,children:e})},$=()=>{const e=q.useContext(U);if(e===void 0||e===D)throw new Error("useKelviq must be used within an initialized KelviqProvider.");return e},M=({featureKey:e,type:i,children:t,fallback:r=null,loadingComponent:y,condition:o})=>{const{getEntitlement:L,isLoading:v,error:K,allEntitlements:E}=$(),f=L(e,i);return f.isLoading||v&&!f.data&&!f.error&&!E.data&&!E.error?l.jsx(l.Fragment,{children:y!==void 0?y:r}):f.error||K&&!f.data?l.jsx(l.Fragment,{children:r}):!f.data||!f.data.hasAccess||o&&!o(f.data)?l.jsx(l.Fragment,{children:r}):typeof t=="function"?l.jsx(l.Fragment,{children:t(f.data)}):l.jsx(l.Fragment,{children:t})},N=({children:e,...i})=>l.jsx(M,{...i,type:"customizable",children:t=>t.hasAccess&&t.configuration!==null&&typeof t.configuration=="number"?e(t.configuration):l.jsx(l.Fragment,{children:i.fallback||null})}),j=e=>{const i=t=>t.hasAccess&&(t.remaining===null||t.remaining>0);return l.jsx(M,{...e,type:"metered",condition:e.condition||i})},W=e=>l.jsx(M,{...e,type:"boolean"}),G=()=>{const{allEntitlements:e}=$();return e},z=e=>{const{getEntitlement:i}=$();return i(e,"boolean")},H=e=>{const{getEntitlement:i}=$();return i(e,"customizable")},X=e=>{const{getEntitlement:i}=$();return i(e,"metered")};c.KelviqContext=U,c.KelviqProvider=x,c.ShowWhenBooleanEntitled=W,c.ShowWhenConfigEntitled=N,c.ShowWhenMeteredEntitled=j,c.defaultKelviqContextValue=D,c.useAllEntitlements=G,c.useBooleanEntitlement=z,c.useConfigEntitlement=H,c.useKelviq=$,c.useMeteredEntitlement=X,Object.defineProperty(c,Symbol.toStringTag,{value:"Module"})});

package/dist/services/makeRequest.service.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Configuration for an API request.
+ * @template ReqBody The type of the request body.
+ */
+export interface ApiRequestConfig<ReqBody = any> {
+    /** The URL for the request. */
+    url: string;
+    /** HTTP method (GET, POST, PUT, DELETE, etc.). Defaults to GET. */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD';
+    /** Custom headers for the request. */
+    headers?: Record<string, string>;
+    /** Data to be sent as the request body. */
+    body?: ReqBody;
+    /** Timeout for the request in milliseconds. Defaults to 5000ms. */
+    timeout?: number;
+    /** Maximum number of retry attempts for failed requests. Defaults to 3. */
+    maxRetries?: number;
+    /** Base delay (in milliseconds) for exponential backoff between retries. Defaults to 1000ms. */
+    backoffBaseDelay?: number;
+    /** Optional: The static authentication token string. */
+    accessToken?: string | null;
+    /** Optional: Query parameters to be appended to the URL. */
+    queryParams?: Record<string, string | number | boolean | undefined>;
+}
+/**
+ * Represents the structure of a successful API response.
+ * @template ResData The type of the data in the response body.
+ */
+export interface ApiResponse<ResData> {
+    /** HTTP status code of the response. */
+    status: number;
+    /** HTTP status text of the response. */
+    statusText: string;
+    /** Parsed data from the response body. */
+    data: ResData;
+}
+/**
+ * Makes an HTTP request using XMLHttpRequest with support for retries and exponential backoff.
+ * @template ResData The expected type of the data in the API response.
+ * @template ReqBody The type of the request body.
+ * @param config Configuration object for the API request.
+ * @returns A Promise that resolves to an ApiResponse<ResData> or rejects with an Error.
+ */
+export declare function apiRequest<ResData = any, ReqBody = any>(config: ApiRequestConfig<ReqBody>): Promise<ApiResponse<ResData>>;

package/dist/types/api.types.d.ts

@@ -0,0 +1,39 @@
+/** Base interface for raw entitlement objects coming from the API. */
+interface RawEntitlement {
+    /** The unique identifier for the feature from the backend. */
+    featureId: string;
+    /** The type of the feature, used to determine how to process it. */
+    featureType: 'BOOLEAN' | 'CUSTOMIZABLE' | 'METER';
+    /** Indicates if the user is entitled to this feature. */
+    hasAccess: boolean;
+}
+export interface RawBooleanEntitlementData extends RawEntitlement {
+    featureType: 'BOOLEAN';
+}
+export interface RawConfigEntitlementData extends RawEntitlement {
+    featureType: 'CUSTOMIZABLE';
+    /** The numeric configuration value associated with the feature, if applicable. */
+    value?: number;
+}
+export interface RawMeteredEntitlementData extends RawEntitlement {
+    featureType: 'METER';
+    /** ISO 8601 string indicating when the usage counter resets, if applicable. */
+    resetAt?: string | null;
+    /** If true, the limit is a hard cap. If false, it might be a soft limit. */
+    hardLimit?: boolean;
+    /** The maximum usage allowed. Can be null for unlimited. */
+    usageLimit: number | null;
+    /** The current usage count. */
+    currentUsage: number;
+}
+/** Union type for any raw entitlement object received from the API. */
+export type AnyRawEntitlementData = RawBooleanEntitlementData | RawConfigEntitlementData | RawMeteredEntitlementData;
+/**
+ * Represents the expected raw API response structure when fetching all entitlements.
+ * Example: { "customer_id": "128", "entitlements": [...] }
+ */
+export interface RawEntitlementsApiResponse {
+    customer_id: string;
+    entitlements: AnyRawEntitlementData[];
+}
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Represents the state of an asynchronous data fetching operation.
+ * @template T The type of the data being fetched.
+ */
+export interface AsyncState<T> {
+    data: T | null;
+    isLoading: boolean;
+    error: Error | null;
+}

package/dist/types/sdk.types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Represents the state of an asynchronous data fetching operation.
+ * @template T The type of the data being fetched.
+ */
+export interface AsyncState<T> {
+    data: T | null;
+    isLoading: boolean;
+    error: Error | null;
+}
+/** Base interface for all processed entitlements within the SDK. */
+export interface Entitlement {
+    /** The unique key identifying the feature (mapped from `feature`). */
+    featureKey: string;
+    /** True if the user has access to this feature, false otherwise (mapped from `enabled`). */
+    hasAccess: boolean;
+    /** The standardized type of the entitlement for SDK logic. */
+    type: 'boolean' | 'customizable' | 'metered';
+}
+/** Represents a processed boolean entitlement. */
+export interface BooleanEntitlement extends Entitlement {
+    type: 'boolean';
+}
+/** Represents a processed configuration entitlement. */
+export interface ConfigEntitlement extends Entitlement {
+    type: 'customizable';
+    /** The numeric configuration value. Null if not applicable or not provided. */
+    configuration: number | null;
+}
+/** Represents a processed metered entitlement. */
+export interface MeteredEntitlement extends Entitlement {
+    type: 'metered';
+    /** The usage limit for the feature. Null if unlimited. */
+    limit: number | null;
+    /** The current usage count. */
+    used: number;
+    /** The remaining usage (limit - used). Null if limit is null. */
+    remaining: number | null;
+    /** ISO 8601 string for when the meter resets. */
+    resetAt?: string | null;
+    /** Indicates if the limit is a hard cap. */
+    hardLimit?: boolean;
+}
+/** Union type for any processed entitlement object used within the SDK. */
+export type AnyEntitlement = BooleanEntitlement | ConfigEntitlement | MeteredEntitlement;
+/**
+ * Type for the cached and processed entitlements data stored by the provider.
+ * It's a map where keys are featureKeys and values are the processed entitlement objects,
+ * allowing for efficient O(1) lookups.
+ */
+export type EntitlementMap = Record<string, AnyEntitlement>;
+/** Optional behavioral configuration options for the KelviqProvider. */
+export interface KelviqApiBehaviorOptions {
+    /** Optional callback for handling errors that occur within the SDK during entitlement fetching. */
+    onError?: (error: Error) => void;
+    /** Optional: Maximum number of retries for API requests. Defaults to 3. */
+    maxRetries?: number;
+    /** Optional: Timeout for API requests in milliseconds. Defaults to 5000. */
+    timeout?: number;
+    /**
+     * If true (default), fetches all entitlements when the provider mounts.
+     * Set to false to manually control the initial fetch using `refreshAllEntitlements`.
+     */
+    fetchEntitlementsOnMount?: boolean;
+    /** Optional: Base delay (in milliseconds) for exponential backoff strategy in retries.
+     * If not provided, the `apiRequest` service's default will be used.
+     */
+    backoffBaseDelay?: number;
+}

package/dist/utils/index.d.ts

@@ -0,0 +1 @@
+export * from './transformations';

package/dist/utils/transformations.d.ts

@@ -0,0 +1,10 @@
+import { RawEntitlementsApiResponse } from '../types/api.types';
+import { EntitlementMap } from '../types/sdk.types';
+/**
+ * Transforms the raw API response for entitlements into a more usable
+ * and structured format (EntitlementMap) for the SDK.
+ * This function maps API field names to SDK-standard field names and calculates derived values.
+ * @param apiResponse The raw response from the entitlements API.
+ * @returns An EntitlementMap: a map of feature keys to their processed entitlement objects.
+ */
+export declare function transformApiEntitlements(apiResponse: RawEntitlementsApiResponse): EntitlementMap;

package/package.json

@@ -0,0 +1,71 @@
+{
+    "name": "@kelviq/react-sdk",
+    "private": false,
+    "version": "0.0.1-beta",
+    "type": "module",
+    "main": "dist/kelviq-react-sdk.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist",
+        "package.json",
+        "README.md"
+    ],
+    "scripts": {
+        "dev": "vite",
+        "build": "tsc -b ./tsconfig.lib.json && vite build",
+        "lint": "eslint .",
+        "preview": "vite preview",
+        "prepublishOnly": "npm run build",
+        "test": "vitest",
+        "test:ui": "vitest --ui",
+        "coverage": "vitest run --coverage",
+        "precommit": "lint-staged",
+        "commitlint": "commitlint --edit",
+        "commit": "git-cz",
+        "prepare": "husky install"
+    },
+    "lint-staged": {
+        "{src,test}/**/*.{ts,tsx}": [
+            "prettier --write",
+            "eslint --fix"
+        ]
+    },
+    "config": {
+        "commitizen": {
+            "path": "cz-conventional-changelog"
+        }
+    },
+    "peerDependencies": {
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0"
+    },
+    "devDependencies": {
+        "@commitlint/cli": "^19.8.1",
+        "@commitlint/config-conventional": "^19.8.1",
+        "@eslint/js": "^9.15.0",
+        "@testing-library/jest-dom": "^6.6.3",
+        "@testing-library/react": "^16.3.0",
+        "@types/node": "^22.10.2",
+        "@types/react": "^18.3.12",
+        "@types/react-dom": "^18.3.1",
+        "@vitejs/plugin-react-swc": "^3.5.0",
+        "@vitest/ui": "^3.1.3",
+        "commitizen": "^4.3.1",
+        "cz-conventional-changelog": "^3.3.0",
+        "eslint": "^9.15.0",
+        "eslint-plugin-react-hooks": "^5.0.0",
+        "eslint-plugin-react-refresh": "^0.4.14",
+        "globals": "^15.12.0",
+        "husky": "^9.1.7",
+        "jsdom": "^26.1.0",
+        "lint-staged": "^16.0.0",
+        "prettier": "^3.5.3",
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0",
+        "typescript": "~5.6.2",
+        "typescript-eslint": "^8.15.0",
+        "vite": "^6.0.1",
+        "vite-plugin-dts": "^4.3.0",
+        "vitest": "^3.1.3"
+    }
+}