@dinoconfig/js-sdk 1.0.0

package/lib/cache/cache-manager.d.ts

@@ -0,0 +1,86 @@
+import { CacheConfig, CacheOptions, CacheStats } from './cache.types';
+/**
+ * Multi-layer cache manager.
+ * Provides a unified interface for caching with L1 (memory) and L2 (storage) layers.
+ *
+ * @class CacheManager
+ * @example
+ * ```typescript
+ * const cache = new CacheManager({
+ *   enabled: true,
+ *   ttl: 60000,
+ *   maxSize: 1000,
+ *   storage: 'localStorage',
+ * });
+ *
+ * // Get with automatic fallback through layers
+ * const value = await cache.get('key');
+ *
+ * // Set (writes to both layers)
+ * await cache.set('key', 'value');
+ *
+ * // Invalidate
+ * cache.invalidate('brand:.*');
+ * ```
+ */
+export declare class CacheManager {
+    private config;
+    private memoryCache;
+    private storageCache?;
+    constructor(config: CacheConfig);
+    /**
+     * Get a value from cache.
+     * Checks L1 (memory) first, then L2 (storage) if available.
+     *
+     * @param {string} key - Cache key
+     * @returns {Promise<T | null>} Cached value or null if not found
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Set a value in cache.
+     * Writes to both L1 (memory) and L2 (storage) if available.
+     *
+     * @param {string} key - Cache key
+     * @param {T} value - Value to cache
+     * @param {CacheOptions} options - Optional cache options
+     */
+    set<T>(key: string, value: T, options?: CacheOptions): Promise<void>;
+    /**
+     * Delete a value from cache.
+     * Removes from both L1 and L2.
+     *
+     * @param {string} key - Cache key
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all cache entries.
+     */
+    clear(): Promise<void>;
+    /**
+     * Invalidate entries matching a pattern.
+     *
+     * @param {string} pattern - Regex pattern to match keys
+     */
+    invalidate(pattern?: string): Promise<void>;
+    /**
+     * Check if a key exists in cache.
+     *
+     * @param {string} key - Cache key
+     * @returns {boolean} True if key exists and is not expired
+     */
+    has(key: string): boolean;
+    /**
+     * Get cache statistics.
+     *
+     * @returns {CacheStats} Cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Prefetch a value into cache.
+     * This is a convenience method for warming the cache.
+     *
+     * @param {string} key - Cache key
+     * @param {() => Promise<T>} fetcher - Function to fetch the value if not cached
+     */
+    prefetch<T>(key: string, fetcher: () => Promise<T>): Promise<T>;
+}

package/lib/cache/cache.types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview Type definitions for the cache layer.
+ * @module @dinoconfig/dinoconfig-js-sdk/cache/types
+ */
+/**
+ * Configuration options for the cache layer.
+ *
+ * @interface CacheConfig
+ * @example
+ * ```typescript
+ * const cacheConfig: CacheConfig = {
+ *   enabled: true,
+ *   ttl: 60000,           // 1 minute
+ *   maxSize: 1000,
+ *   storage: 'localStorage',
+ *   staleWhileRevalidate: true,
+ * };
+ * ```
+ */
+export interface CacheConfig {
+    /**
+     * Whether caching is enabled.
+     * @default false
+     */
+    enabled: boolean;
+    /**
+     * Time-to-live in milliseconds.
+     * How long cached entries remain valid.
+     * @default 60000 (1 minute)
+     */
+    ttl: number;
+    /**
+     * Maximum number of entries in memory cache.
+     * @default 1000
+     */
+    maxSize: number;
+    /**
+     * Storage backend for L2 cache.
+     * - 'memory': Only use in-memory cache (L1)
+     * - 'localStorage': Use localStorage for persistent cache (L2)
+     * - 'indexedDB': Use IndexedDB for persistent cache (L2)
+     * @default undefined (memory only)
+     */
+    storage?: 'memory' | 'localStorage' | 'indexedDB';
+    /**
+     * Whether to return stale data while fetching fresh data in background.
+     * @default false
+     */
+    staleWhileRevalidate?: boolean;
+}
+/**
+ * A cached entry with metadata.
+ *
+ * @interface CacheEntry
+ * @typeParam T - The type of the cached value
+ */
+export interface CacheEntry<T = any> {
+    /**
+     * The cached value.
+     */
+    value: T;
+    /**
+     * Timestamp when the entry was created.
+     */
+    timestamp: number;
+    /**
+     * Timestamp when the entry expires.
+     */
+    expiresAt: number;
+    /**
+     * Optional version number for cache invalidation.
+     */
+    version?: number;
+}
+/**
+ * Options for cache operations.
+ */
+export interface CacheOptions {
+    /**
+     * Custom TTL for this specific operation.
+     * Overrides the default TTL from cache configuration.
+     */
+    ttl?: number;
+}
+/**
+ * Cache statistics.
+ */
+export interface CacheStats {
+    /**
+     * Number of cache hits.
+     */
+    hits: number;
+    /**
+     * Number of cache misses.
+     */
+    misses: number;
+    /**
+     * Number of entries currently in cache.
+     */
+    size: number;
+    /**
+     * Cache hit rate (0-1).
+     */
+    hitRate: number;
+}

package/lib/cache/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Cache layer exports.
+ * @module @dinoconfig/dinoconfig-js-sdk/cache
+ */
+export { CacheManager } from './cache-manager';
+export { MemoryCache } from './memory-cache';
+export { StorageCache } from './storage-cache';
+export type { CacheConfig, CacheEntry, CacheOptions, CacheStats, } from './cache.types';

package/lib/cache/memory-cache.d.ts

@@ -0,0 +1,86 @@
+import { CacheOptions } from './cache.types';
+/**
+ * In-memory cache implementation.
+ * Provides fast, synchronous access to cached values.
+ *
+ * @class MemoryCache
+ * @example
+ * ```typescript
+ * const cache = new MemoryCache({ ttl: 60000, maxSize: 1000 });
+ *
+ * await cache.set('key', 'value');
+ * const value = await cache.get('key'); // 'value'
+ * ```
+ */
+export declare class MemoryCache {
+    private ttl;
+    private maxSize;
+    private cache;
+    private hits;
+    private misses;
+    constructor(ttl: number, maxSize: number);
+    /**
+     * Get a value from the cache.
+     *
+     * @param {string} key - Cache key
+     * @returns {T | null} Cached value or null if not found/expired
+     */
+    get<T>(key: string): T | null;
+    /**
+     * Set a value in the cache.
+     *
+     * @param {string} key - Cache key
+     * @param {T} value - Value to cache
+     * @param {CacheOptions} options - Optional cache options
+     */
+    set<T>(key: string, value: T, options?: CacheOptions): void;
+    /**
+     * Delete a value from the cache.
+     *
+     * @param {string} key - Cache key
+     */
+    delete(key: string): void;
+    /**
+     * Clear all entries from the cache.
+     */
+    clear(): void;
+    /**
+     * Invalidate entries matching a pattern.
+     *
+     * @param {string} pattern - Regex pattern to match keys
+     */
+    invalidate(pattern: string): void;
+    /**
+     * Check if an entry exists and is not expired.
+     *
+     * @param {string} key - Cache key
+     * @returns {boolean} True if entry exists and is valid
+     */
+    has(key: string): boolean;
+    /**
+     * Get cache statistics.
+     *
+     * @returns {CacheStats} Cache statistics
+     */
+    getStats(): {
+        hits: number;
+        misses: number;
+        size: number;
+        hitRate: number;
+    };
+    /**
+     * Check if an entry is expired.
+     *
+     * @private
+     * @param {CacheEntry} entry - Cache entry
+     * @returns {boolean} True if expired
+     */
+    private isExpired;
+    /**
+     * Evict the oldest entry from the cache.
+     * Uses LRU-like strategy based on expiration time.
+     *
+     * @private
+     */
+    private evictOldest;
+}

package/lib/cache/storage-cache.d.ts

@@ -0,0 +1,58 @@
+import { CacheOptions } from './cache.types';
+/**
+ * Storage cache implementation.
+ * Provides persistent caching using browser storage APIs.
+ *
+ * @class StorageCache
+ * @example
+ * ```typescript
+ * const cache = new StorageCache('localStorage');
+ *
+ * await cache.set('key', 'value');
+ * const value = await cache.get('key'); // 'value'
+ * ```
+ */
+export declare class StorageCache {
+    private adapter;
+    private prefix;
+    constructor(storageType: 'localStorage' | 'indexedDB');
+    /**
+     * Get a value from storage cache.
+     *
+     * @param {string} key - Cache key
+     * @returns {Promise<T | null>} Cached value or null if not found/expired
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Set a value in storage cache.
+     *
+     * @param {string} key - Cache key
+     * @param {T} value - Value to cache
+     * @param {CacheOptions} options - Optional cache options
+     */
+    set<T>(key: string, value: T, options?: CacheOptions): Promise<void>;
+    /**
+     * Delete a value from storage cache.
+     *
+     * @param {string} key - Cache key
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all entries from storage cache.
+     */
+    clear(): Promise<void>;
+    /**
+     * Invalidate entries matching a pattern.
+     *
+     * @param {string} pattern - Regex pattern to match keys
+     */
+    invalidate(pattern: string): Promise<void>;
+    /**
+     * Check if an entry is expired.
+     *
+     * @private
+     * @param {CacheEntry} entry - Cache entry
+     * @returns {boolean} True if expired
+     */
+    private isExpired;
+}

package/lib/config-api.d.ts

@@ -0,0 +1,111 @@
+import { HttpClient } from './http-client';
+import { ApiResponse, RequestOptions } from './types';
+import { CacheManager } from './cache/cache-manager';
+/**
+ * Full configuration data returned by the API.
+ * @template T - The shape of the configuration values (defaults to Record<string, unknown>)
+ */
+export interface ConfigData<T = Record<string, unknown>> {
+    readonly name: string;
+    readonly description?: string;
+    readonly values: Readonly<T>;
+    readonly version: number;
+    readonly keys: readonly string[];
+    readonly createdAt: Date;
+    readonly updatedAt?: Date;
+}
+/**
+ * Configuration API class for interacting with DinoConfig configurations.
+ *
+ * This class provides methods to retrieve configuration values from the
+ * DinoConfig API. It handles request formatting, error handling, response
+ * parsing, and caching automatically.
+ *
+ * @class ConfigAPI
+ * @example
+ * ```typescript
+ * const dinoconfig = await dinoconfigApi({ apiKey: 'dino_...' });
+ *
+ * // Get entire config
+ * const config = await dinoconfig.configs.get('MyBrand', 'AppSettings');
+ * console.log('All values:', config.data.values);
+ *
+ * // Get single value (shorthand)
+ * const theme = await dinoconfig.configs.getValue('MyBrand.AppSettings.theme');
+ * console.log('Theme:', theme.data);
+ * ```
+ */
+export declare class ConfigAPI {
+    private readonly httpClient;
+    private readonly cacheManager?;
+    constructor(httpClient: HttpClient, cacheManager?: CacheManager | undefined);
+    /**
+     * Retrieves an entire configuration with all its values.
+     *
+     * @template T - The shape of the configuration values for type safety
+     * @example
+     * ```typescript
+     * // Shorthand: get('Brand.Config')
+     * const config = await dinoconfig.configs.get('Acme.AppSettings');
+     *
+     * // Full params: get(brand, config)
+     * const config = await dinoconfig.configs.get('Acme', 'AppSettings');
+     * console.log(config.data.values);
+     *
+     * // With generated types for full type safety
+     * import { DinoConfig } from './types/dinoconfig';
+     * const config = await dinoconfig.configs.get<DinoConfig.Acme.AppSettings>('Acme', 'AppSettings');
+     * config.data.values.theme; // fully typed!
+     * ```
+     */
+    get<T = Record<string, unknown>>(path: string, options?: RequestOptions): Promise<ApiResponse<ConfigData<T>>>;
+    get<T = Record<string, unknown>>(brandName: string, configName: string, options?: RequestOptions): Promise<ApiResponse<ConfigData<T>>>;
+    /**
+     * Retrieves a specific configuration value from DinoConfig.
+     *
+     * @template T - The expected type of the value for type safety
+     * @example
+     * ```typescript
+     * // Shorthand: getValue('Brand.Config.Key')
+     * const response = await dinoconfig.configs.getValue('Acme.AppSettings.theme');
+     *
+     * // Full params: getValue(brand, config, key)
+     * const response = await dinoconfig.configs.getValue('Acme', 'AppSettings', 'theme');
+     * console.log('Theme:', response.data);
+     *
+     * // With type parameter for type safety
+     * const theme = await dinoconfig.configs.getValue<string>('Acme', 'AppSettings', 'theme');
+     * const maxUsers = await dinoconfig.configs.getValue<number>('Acme', 'AppSettings', 'maxUsers');
+     * ```
+     */
+    getValue<T = unknown>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    getValue<T = unknown>(brandName: string, configName: string, keyName: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Parses arguments for the get() method.
+     */
+    private parseConfigArgs;
+    /**
+     * Parses arguments for the getValue() method.
+     */
+    private parseValueArgs;
+    /**
+     * Parses a dot-notation path into components.
+     */
+    private parsePath;
+    /**
+     * Builds the URL for fetching an entire config.
+     */
+    private buildConfigUrl;
+    /**
+     * Builds the URL for fetching a single value.
+     */
+    private buildValueUrl;
+    /**
+     * URL-encodes a path segment.
+     */
+    private encode;
+    /**
+     * Transforms the backend response to the public ConfigData shape.
+     */
+    private transformConfigResponse;
+}

package/lib/dinoconfig-js-sdk.d.ts

@@ -0,0 +1,140 @@
+import { ConfigAPI } from './config-api';
+import { DiscoveryAPI } from './discovery-api';
+import { DinoConfigSDKConfig } from './types';
+import { CacheStats } from './cache/cache.types';
+/**
+ * Cache API interface.
+ */
+export interface CacheAPI {
+    /**
+     * Get a value from cache.
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Set a value in cache.
+     */
+    set<T>(key: string, value: T, options?: {
+        ttl?: number;
+    }): Promise<void>;
+    /**
+     * Delete a value from cache.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all cache entries.
+     */
+    clear(): Promise<void>;
+    /**
+     * Invalidate entries matching a pattern.
+     */
+    invalidate(pattern?: string): Promise<void>;
+    /**
+     * Prefetch a value into cache.
+     */
+    prefetch<T>(key: string, fetcher: () => Promise<T>): Promise<T>;
+    /**
+     * Get cache statistics.
+     */
+    getStats(): CacheStats;
+}
+/**
+ * DinoConfig SDK instance interface.
+ * Provides access to all SDK APIs through a unified interface.
+ *
+ * @interface DinoConfigInstance
+ * @property {ConfigAPI} configs - API for retrieving configuration values
+ * @property {DiscoveryAPI} discovery - API for discovering brands, configs, and schemas
+ *
+ * @example
+ * ```typescript
+ * const dinoconfig = await dinoconfigApi({ apiKey: 'dino_...' });
+ *
+ * // Get entire config
+ * const config = await dinoconfig.configs.get('Brand.Config');
+ *
+ * // Get single value
+ * const value = await dinoconfig.configs.getValue('Brand.Config.Key');
+ *
+ * // Discovery
+ * const brands = await dinoconfig.discovery.listBrands();
+ *
+ * // Cache management
+ * await dinoconfig.cache.invalidate('brand:.*');
+ * ```
+ */
+export interface DinoConfigInstance {
+    /**
+     * Configuration API for retrieving config values.
+     *
+     * Methods:
+     * - `get(path)` or `get(brand, config)` - Get entire config
+     * - `getValue(path)` or `getValue(brand, config, key)` - Get single value
+     *
+     * @see {@link ConfigAPI}
+     */
+    configs: ConfigAPI;
+    /**
+     * Discovery API for exploring available brands, configs, and schemas.
+     *
+     * Methods:
+     * - `listBrands()` - List all accessible brands
+     * - `listConfigs(brand)` - List configs for a brand
+     * - `getSchema(brand, config)` - Get config schema
+     * - `introspect()` - Full introspection of all data
+     *
+     * @see {@link DiscoveryAPI}
+     */
+    discovery: DiscoveryAPI;
+    /**
+     * Cache API for managing the cache layer.
+     *
+     * @see {@link CacheAPI}
+     */
+    cache: CacheAPI;
+}
+/**
+ * Creates and initializes a new DinoConfig SDK instance.
+ *
+ * This is the main entry point for using the DinoConfig SDK.
+ *
+ * @async
+ * @function dinoconfigApi
+ * @param {DinoConfigSDKConfig} config - Configuration options
+ * @param {string} config.apiKey - Your DinoConfig API key
+ * @param {string} [config.baseUrl='http://localhost:3000'] - API base URL
+ * @param {number} [config.timeout=10000] - Request timeout in milliseconds
+ * @returns {Promise<DinoConfigInstance>} Initialized SDK instance
+ * @throws {Error} If API key exchange fails or network error occurs
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { dinoconfigApi } from '@dinoconfig/dinoconfig-js-sdk';
+ *
+ * const dinoconfig = await dinoconfigApi({
+ *   apiKey: 'dino_your-api-key-here'
+ * });
+ *
+ * // Get config value
+ * const response = await dinoconfig.configs.getValue('Brand.Config.Key');
+ * console.log(response.data);
+ * ```
+ *
+ * @example With all options
+ * ```typescript
+ * const dinoconfig = await dinoconfigApi({
+ *   apiKey: process.env.DINOCONFIG_API_KEY!,
+ *   baseUrl: 'https://api.dinoconfig.com',
+ *   timeout: 15000
+ * });
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * try {
+ *   const dinoconfig = await dinoconfigApi({ apiKey: '...' });
+ * } catch (error) {
+ *   console.error('Failed to initialize:', error);
+ * }
+ * ```
+ */
+export declare function dinoconfigApi(config: DinoConfigSDKConfig): Promise<DinoConfigInstance>;