@dinoconfig/js-sdk 1.0.0

package/lib/discovery-api.d.ts

@@ -0,0 +1,174 @@
+import { HttpClient } from './http-client';
+import { ApiResponse, RequestOptions } from './types';
+/**
+ * Information about a brand in DinoConfig.
+ */
+export interface BrandInfo {
+    readonly name: string;
+    readonly description?: string;
+    readonly configCount: number;
+    readonly createdAt: Date;
+}
+/**
+ * Information about a configuration in DinoConfig.
+ */
+export interface ConfigInfo {
+    readonly name: string;
+    readonly description?: string;
+    readonly keys: readonly string[];
+    readonly version: number;
+    readonly createdAt: Date;
+}
+/** Supported field types in DinoConfig schemas */
+export type FieldType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+/**
+ * Validation rules for a configuration field.
+ */
+export interface FieldValidation {
+    readonly min?: number;
+    readonly max?: number;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly pattern?: string;
+    readonly enum?: readonly unknown[];
+}
+/**
+ * Schema definition for a configuration field.
+ */
+export interface FieldSchema {
+    readonly type: FieldType;
+    readonly description?: string;
+    readonly defaultValue?: unknown;
+    readonly required?: boolean;
+    readonly validation?: FieldValidation;
+}
+/**
+ * Complete schema for a configuration.
+ */
+export interface ConfigSchema {
+    readonly configName: string;
+    readonly version: number;
+    readonly fields: Readonly<Record<string, FieldSchema>>;
+}
+/**
+ * Key information with type and value.
+ */
+export interface KeyInfo {
+    readonly name: string;
+    readonly type: string;
+    readonly value: unknown;
+}
+/**
+ * Configuration information with key details.
+ */
+export interface ConfigInfoDetail {
+    readonly name: string;
+    readonly description?: string;
+    readonly keys: readonly KeyInfo[];
+    readonly version: number;
+}
+/**
+ * Brand information with config details.
+ */
+export interface BrandInfoDetail {
+    readonly name: string;
+    readonly description?: string;
+    readonly configs: readonly ConfigInfoDetail[];
+}
+/**
+ * Full introspection result containing all brands, configs, and keys.
+ */
+export interface IntrospectionResult {
+    readonly company: string;
+    readonly brands: readonly BrandInfoDetail[];
+    readonly generatedAt: Date;
+}
+/**
+ * Discovery API class for interacting with DinoConfig discovery endpoints.
+ *
+ * @class DiscoveryAPI
+ * @example
+ * ```typescript
+ * const dinoconfig = await dinoconfigApi({ apiKey: 'dino_...' });
+ *
+ * // List all brands
+ * const brands = await dinoconfig.discovery.listBrands();
+ *
+ * // List configs for a brand
+ * const configs = await dinoconfig.discovery.listConfigs('MyBrand');
+ *
+ * // Get config schema
+ * const schema = await dinoconfig.discovery.getSchema('MyBrand', 'FeatureFlags');
+ * ```
+ */
+export declare class DiscoveryAPI {
+    private readonly httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Lists all brands accessible by the current API key.
+     *
+     * @example
+     * ```typescript
+     * const response = await dinoconfig.discovery.listBrands();
+     * response.data.forEach(brand => {
+     *   console.log(`${brand.name}: ${brand.configCount} configs`);
+     * });
+     * ```
+     */
+    listBrands(options?: RequestOptions): Promise<ApiResponse<BrandInfo[]>>;
+    /**
+     * Lists all configurations for a specific brand.
+     *
+     * @example
+     * ```typescript
+     * const response = await dinoconfig.discovery.listConfigs('MyBrand');
+     * response.data.forEach(config => {
+     *   console.log(`${config.name}: ${config.keys.length} keys`);
+     * });
+     * ```
+     */
+    listConfigs(brandName: string, options?: RequestOptions): Promise<ApiResponse<ConfigInfo[]>>;
+    /**
+     * Gets the schema/structure for a specific configuration.
+     *
+     * @example
+     * ```typescript
+     * const response = await dinoconfig.discovery.getSchema('MyBrand', 'FeatureFlags');
+     * Object.entries(response.data.fields).forEach(([name, field]) => {
+     *   console.log(`${name}: ${field.type}`);
+     * });
+     * ```
+     */
+    getSchema(brandName: string, configName: string, options?: RequestOptions): Promise<ApiResponse<ConfigSchema>>;
+    /**
+     * Performs full introspection, returning all brands, configs, and keys.
+     *
+     * @example
+     * ```typescript
+     * const response = await dinoconfig.discovery.introspect();
+     * response.data.brands.forEach(brand => {
+     *   console.log(`Brand: ${brand.name}`);
+     *   brand.configs.forEach(config => {
+     *     console.log(`  Config: ${config.name} (${config.keys.length} keys)`);
+     *   });
+     * });
+     * ```
+     */
+    introspect(options?: RequestOptions): Promise<ApiResponse<IntrospectionResult>>;
+    /**
+     * Builds URL path for brand-level endpoints.
+     */
+    private buildBrandUrl;
+    /**
+     * Builds URL path for config-level endpoints.
+     */
+    private buildConfigUrl;
+    /**
+     * URL-encodes a path segment.
+     */
+    private encode;
+    /**
+     * Extracts and transforms response data.
+     */
+    private extractData;
+}

package/lib/http-client.d.ts

@@ -0,0 +1,245 @@
+import { ApiResponse, RequestOptions } from './types';
+/**
+ * HTTP client for making requests to the DinoConfig API.
+ *
+ * This class handles:
+ * - API key to token exchange
+ * - Authorization header management
+ * - Request/response formatting
+ * - Timeout handling
+ * - Retry logic with exponential backoff
+ *
+ * @class HttpClient
+ * @internal This class is used internally by the SDK
+ *
+ * @example
+ * ```typescript
+ * // Internal usage - not typically used directly
+ * const client = new HttpClient('https://api.dinoconfig.com', 10000);
+ * await client.configureAuthorizationHeader({ 'X-API-Key': 'dino_...' });
+ * const response = await client.get('/api/endpoint');
+ * ```
+ */
+export declare class HttpClient {
+    /**
+     * Base URL for all API requests.
+     * @private
+     */
+    private baseUrl;
+    /**
+     * Default timeout for requests in milliseconds.
+     * @private
+     */
+    private defaultTimeout;
+    /**
+     * Default headers included in every request.
+     * @private
+     */
+    private defaultHeaders;
+    /**
+     * Creates a new HttpClient instance.
+     *
+     * @param {string} baseUrl - The base URL of the DinoConfig API
+     * @param {number} [timeout=10000] - Default request timeout in milliseconds
+     *
+     * @example
+     * ```typescript
+     * const client = new HttpClient('https://api.dinoconfig.com', 15000);
+     * ```
+     */
+    constructor(baseUrl: string, timeout?: number);
+    /**
+     * Configures authorization by exchanging the API key for an access token.
+     *
+     * This method:
+     * 1. Extracts the API key from the provided headers
+     * 2. Exchanges it for a JWT access token
+     * 3. Configures the Authorization header for subsequent requests
+     *
+     * @async
+     * @method configureAuthorizationHeader
+     * @param {Record<string, string>} headers - Headers containing the X-API-Key
+     * @returns {Promise<void>}
+     * @throws {Error} If token exchange fails
+     *
+     * @example
+     * ```typescript
+     * await client.configureAuthorizationHeader({
+     *   'X-API-Key': 'dino_your-api-key-here'
+     * });
+     * // Client is now authenticated
+     * ```
+     */
+    configureAuthorizationHeader(headers: Record<string, string>): Promise<void>;
+    /**
+     * Exchanges an API key for a JWT access token.
+     *
+     * Makes a POST request to the token exchange endpoint with the API key
+     * and returns the access token from the response.
+     *
+     * @async
+     * @private
+     * @method exchangeApiKeyForToken
+     * @param {string} apiKey - The API key to exchange
+     * @returns {Promise<string>} The JWT access token
+     * @throws {Error} If the exchange fails or the API key is invalid
+     *
+     * @remarks
+     * The API key is sent via HTTPS, which encrypts it in transit.
+     * The server validates the key and returns a short-lived access token.
+     */
+    private exchangeApiKeyForToken;
+    /**
+     * Makes an HTTP request to the API.
+     *
+     * Handles:
+     * - Request formatting and headers
+     * - Timeout via AbortController
+     * - Response parsing
+     * - Error handling
+     * - Retry logic with exponential backoff
+     *
+     * @async
+     * @private
+     * @method request
+     * @typeParam T - The expected response data type
+     * @param {string} method - HTTP method (GET, POST, PUT, PATCH, DELETE)
+     * @param {string} endpoint - API endpoint path (e.g., '/api/configs')
+     * @param {any} [data] - Request body data (for POST, PUT, PATCH)
+     * @param {RequestOptions} [options={}] - Request customization options
+     * @returns {Promise<ApiResponse<T>>} The API response
+     * @throws {ApiError} If the request fails after all retries
+     */
+    private request;
+    /**
+     * Makes a GET request to the specified endpoint.
+     *
+     * @async
+     * @method get
+     * @typeParam T - The expected response data type
+     * @param {string} endpoint - The API endpoint path
+     * @param {RequestOptions} [options] - Optional request configuration
+     * @returns {Promise<ApiResponse<T>>} The API response
+     *
+     * @example
+     * ```typescript
+     * const response = await client.get<Config>('/api/configs/123');
+     * console.log(response.data.name);
+     * ```
+     */
+    get<T>(endpoint: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Makes a POST request to the specified endpoint.
+     *
+     * @async
+     * @method post
+     * @typeParam T - The expected response data type
+     * @param {string} endpoint - The API endpoint path
+     * @param {any} [data] - The request body data
+     * @param {RequestOptions} [options] - Optional request configuration
+     * @returns {Promise<ApiResponse<T>>} The API response
+     *
+     * @example
+     * ```typescript
+     * const response = await client.post<Config>('/api/configs', {
+     *   name: 'NewConfig',
+     *   formData: { key: 'value' }
+     * });
+     * ```
+     */
+    post<T>(endpoint: string, data?: any, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Makes a PUT request to the specified endpoint.
+     *
+     * @async
+     * @method put
+     * @typeParam T - The expected response data type
+     * @param {string} endpoint - The API endpoint path
+     * @param {any} [data] - The request body data
+     * @param {RequestOptions} [options] - Optional request configuration
+     * @returns {Promise<ApiResponse<T>>} The API response
+     *
+     * @example
+     * ```typescript
+     * const response = await client.put<Config>('/api/configs/123', {
+     *   name: 'UpdatedConfig'
+     * });
+     * ```
+     */
+    put<T>(endpoint: string, data?: any, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Makes a PATCH request to the specified endpoint.
+     *
+     * @async
+     * @method patch
+     * @typeParam T - The expected response data type
+     * @param {string} endpoint - The API endpoint path
+     * @param {any} [data] - The request body data (partial update)
+     * @param {RequestOptions} [options] - Optional request configuration
+     * @returns {Promise<ApiResponse<T>>} The API response
+     *
+     * @example
+     * ```typescript
+     * const response = await client.patch<Config>('/api/configs/123', {
+     *   formData: { updatedKey: 'newValue' }
+     * });
+     * ```
+     */
+    patch<T>(endpoint: string, data?: any, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Makes a DELETE request to the specified endpoint.
+     *
+     * @async
+     * @method delete
+     * @typeParam T - The expected response data type
+     * @param {string} endpoint - The API endpoint path
+     * @param {RequestOptions} [options] - Optional request configuration
+     * @returns {Promise<ApiResponse<T>>} The API response
+     *
+     * @example
+     * ```typescript
+     * const response = await client.delete('/api/configs/123');
+     * ```
+     */
+    delete<T>(endpoint: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Updates the authorization token.
+     *
+     * Use this method if you need to manually update the token
+     * (e.g., after refreshing it externally).
+     *
+     * @method setToken
+     * @param {string} token - The new JWT access token
+     *
+     * @example
+     * ```typescript
+     * client.setToken('new-jwt-token');
+     * ```
+     */
+    setToken(token: string): void;
+    /**
+     * Sets a custom header for all subsequent requests.
+     *
+     * @method setHeader
+     * @param {string} key - The header name
+     * @param {string} value - The header value
+     *
+     * @example
+     * ```typescript
+     * client.setHeader('X-Custom-Header', 'custom-value');
+     * ```
+     */
+    setHeader(key: string, value: string): void;
+    /**
+     * Removes a custom header from subsequent requests.
+     *
+     * @method removeHeader
+     * @param {string} key - The header name to remove
+     *
+     * @example
+     * ```typescript
+     * client.removeHeader('X-Custom-Header');
+     * ```
+     */
+    removeHeader(key: string): void;
+}