@flagvault/sdk
Version:
Lightweight JavaScript SDK for FlagVault with graceful error handling and built-in React hooks for seamless feature flag integration.
208 lines • 6.23 kB
TypeScript
/**
* Base exception for FlagVault SDK errors.
*/
export declare class FlagVaultError extends Error {
constructor(message: string);
}
/**
* Raised when authentication fails.
*/
export declare class FlagVaultAuthenticationError extends FlagVaultError {
constructor(message: string);
}
/**
* Raised when network requests fail.
*/
export declare class FlagVaultNetworkError extends FlagVaultError {
constructor(message: string);
}
/**
* Raised when the API returns an error response.
*/
export declare class FlagVaultAPIError extends FlagVaultError {
constructor(message: string);
}
/**
* Configuration options for the FlagVault SDK.
*
* @group Configuration
*/
export interface FlagVaultSDKConfig {
/**
* API Key for authenticating with the FlagVault service.
* Can be obtained from your FlagVault dashboard.
* Environment is automatically determined from the key prefix (live_ = production, test_ = test).
*/
apiKey: string;
/**
* Request timeout in milliseconds.
* Defaults to 10000ms (10 seconds).
*/
timeout?: number;
/**
* @internal
* Base URL for the FlagVault API.
* Defaults to "https://api.flagvault.com".
*/
baseUrl?: string;
}
/**
* FlagVault SDK for feature flag management.
*
* This SDK allows you to easily integrate feature flags into your JavaScript/TypeScript applications.
* Feature flags (also known as feature toggles) allow you to enable or disable features in your
* application without deploying new code.
*
* ## Installation
*
* ```bash
* npm install @flagvault/sdk
* # or
* yarn add @flagvault/sdk
* ```
*
* ## Basic Usage
*
* ```typescript
* import FlagVaultSDK from '@flagvault/sdk';
*
* const sdk = new FlagVaultSDK({
* apiKey: 'live_your-api-key-here' // Use 'test_' prefix for test environment
* });
*
* // Check if a feature flag is enabled
* const isEnabled = await sdk.isEnabled('my-feature-flag');
* if (isEnabled) {
* // Feature is enabled, run feature code
* } else {
* // Feature is disabled, run fallback code
* }
* ```
*
* ## Graceful Error Handling
*
* The SDK automatically handles errors gracefully by returning default values:
*
* ```typescript
* // No try/catch needed - errors are handled gracefully
* const isEnabled = await sdk.isEnabled('my-feature-flag', false);
*
* // On network error, you'll see:
* // FlagVault: Failed to connect to API for flag 'my-feature-flag', using default: false
*
* // On authentication error:
* // FlagVault: Invalid API credentials for flag 'my-feature-flag', using default: false
*
* // On missing flag:
* // FlagVault: Flag 'my-feature-flag' not found, using default: false
* ```
*
* ## Advanced Error Handling
*
* For custom error handling, you can still catch exceptions for parameter validation:
*
* ```typescript
* try {
* const isEnabled = await sdk.isEnabled('my-feature-flag', false);
* // ...
* } catch (error) {
* // Only throws for invalid parameters (empty flagKey)
* console.error('Parameter validation error:', error.message);
* }
* ```
*
* @group Core
*/
declare class FlagVaultSDK {
private apiKey;
private baseUrl;
private timeout;
/**
* Creates a new instance of the FlagVault SDK.
*
* @param config - Configuration options for the SDK
* @throws Error if apiKey is not provided
*/
constructor(config: FlagVaultSDKConfig);
/**
* Checks if a feature flag is enabled.
*
* @param flagKey - The key for the feature flag
* @param defaultValue - Default value to return on error (defaults to false)
* @returns A promise that resolves to a boolean indicating if the feature is enabled
* @throws Error if flagKey is not provided
*/
isEnabled(flagKey: string, defaultValue?: boolean): Promise<boolean>;
}
export default FlagVaultSDK;
/**
* React hook return type for feature flag hooks.
* @group React Hooks
*/
export interface UseFeatureFlagReturn {
/** Whether the feature flag is enabled */
isEnabled: boolean;
/** Whether the hook is currently loading the flag status */
isLoading: boolean;
/** Any error that occurred while fetching the flag status */
error: Error | null;
}
/**
* React hook for checking feature flag status.
*
* @param sdk - FlagVault SDK instance
* @param flagKey - The feature flag key to check
* @param defaultValue - Default value to use if flag cannot be loaded
* @returns Object containing isEnabled, isLoading, and error states
*
* @example
* ```tsx
* import FlagVaultSDK, { useFeatureFlag } from '@flagvault/sdk';
*
* const sdk = new FlagVaultSDK({ apiKey: 'live_your-api-key' });
*
* function MyComponent() {
* const { isEnabled, isLoading, error } = useFeatureFlag(sdk, 'new-feature', false);
*
* if (isLoading) return <div>Loading...</div>;
* if (error) return <div>Error: {error.message}</div>;
*
* return isEnabled ? <NewFeature /> : <OldFeature />;
* }
* ```
*
* @group React Hooks
*/
export declare function useFeatureFlag(sdk: FlagVaultSDK, flagKey: string, defaultValue?: boolean): UseFeatureFlagReturn;
/**
* React hook for checking feature flag status with caching.
* Reduces API calls by caching flag values for a specified TTL.
*
* @param sdk - FlagVault SDK instance
* @param flagKey - The feature flag key to check
* @param defaultValue - Default value to use if flag cannot be loaded
* @param cacheTTL - Cache time-to-live in milliseconds (default: 5 minutes)
* @returns Object containing isEnabled, isLoading, and error states
*
* @example
* ```tsx
* import FlagVaultSDK, { useFeatureFlagCached } from '@flagvault/sdk';
*
* const sdk = new FlagVaultSDK({ apiKey: 'live_your-api-key' });
*
* function MyComponent() {
* const { isEnabled, isLoading } = useFeatureFlagCached(
* sdk,
* 'new-feature',
* false,
* 300000 // 5 minutes cache
* );
*
* return isEnabled ? <NewFeature /> : <OldFeature />;
* }
* ```
*
* @group React Hooks
*/
export declare function useFeatureFlagCached(sdk: FlagVaultSDK, flagKey: string, defaultValue?: boolean, cacheTTL?: number): UseFeatureFlagReturn;
//# sourceMappingURL=index.d.ts.map