@ritas-inc/hanaqueryapi-client/dist/hana-query-client.d.ts

TypeScript client for HANA Query API with full type safety and error handling

/**
 * HANA Query API Client - Main Client Class
 *
 * Complete TypeScript client for the HANA Query API with full type safety,
 * error handling, retry logic, and logging.
 */
import type { ClientConfig, RequestOptions, SalesParams, HealthData, HealthMetadata, DocsData, DocsMetadata, ItemsStatusData, ItemsStatusMetadata, ItemGroupsData, ItemGroupsMetadata, SalesData, SalesMetadata, HierarchiesData, HierarchiesMetadata, TreesData, TreesMetadata, ProductionSectorsData, ProductionSectorsMetadata, PlansData, PlansMetadata, SinglePlanData, SinglePlanMetadata, PlanProductsData, PlanProductsMetadata, PlanWorkOrdersData, PlanWorkOrdersMetadata, PlanSectorsSummaryData, PlanSectorsSummaryMetadata, AllPlansSectorsSummaryData, AllPlansSectorsSummaryMetadata, UserData, UserMetadata, APIResponse } from './types.ts';
/**
 * Main HANA Query API Client
 */
export declare class HanaQueryClient {
    private readonly config;
    constructor(config: ClientConfig, customConfig?: Partial<Omit<ClientConfig, 'baseUrl'>>);
    /**
     * Get API health status with system information
     *
     * @param options - Optional request configuration
     * @returns Promise resolving to health data and system metadata
     *
     * @example
     * ```typescript
     * const { data, metadata } = await client.getHealth();
     * console.log(`API Status: ${data.status}`);
     * console.log(`Uptime: ${Math.round(data.uptime / 60)} minutes`);
     * console.log(`Node Version: ${metadata.nodeVersion}`);
     * console.log(`Platform: ${metadata.platform}`);
     * ```
     *
     * @returns {Object} result - Health status result
     * @returns {Object} result.data - Health status data
     * @returns {string} result.data.status - Always 'ok' when API is running
     * @returns {string} result.data.timestamp - Current timestamp in ISO 8601 format
     * @returns {number} result.data.uptime - Server uptime in seconds
     * @returns {Object} result.metadata - System information metadata
     * @returns {boolean} result.metadata.systemInfo - Indicates system info is included
     * @returns {string} result.metadata.serverTime - Server current time
     * @returns {string} result.metadata.nodeVersion - Node.js version
     * @returns {string} result.metadata.platform - Operating system platform
     * @returns {string} result.metadata.arch - System architecture
     */
    getHealth(options?: RequestOptions): Promise<{
        data: HealthData;
        metadata: HealthMetadata;
    }>;
    /**
     * Get API documentation with endpoint information
     *
     * @param options - Optional request configuration
     * @returns Promise resolving to API documentation and metadata
     *
     * @example
     * ```typescript
     * const { data, metadata } = await client.getDocs();
     * console.log(`API: ${data.name} v${data.version}`);
     * console.log(`Available endpoints: ${metadata.endpointCount}`);
     * console.log('Endpoints:', Object.keys(data.endpoints));
     * ```
     *
     * @returns {Object} result - API documentation result
     * @returns {Object} result.data - API documentation data
     * @returns {string} result.data.name - API name
     * @returns {string} result.data.version - API version
     * @returns {Object} result.data.endpoints - Map of endpoint paths to descriptions
     * @returns {Object} result.metadata - Documentation metadata
     * @returns {number} result.metadata.endpointCount - Total number of available endpoints
     * @returns {string} result.metadata.apiVersion - API version identifier
     * @returns {string} result.metadata.generatedAt - Documentation generation timestamp
     * @returns {boolean} result.metadata.documentation - Indicates this is documentation endpoint
     */
    getDocs(options?: RequestOptions): Promise<{
        data: DocsData;
        metadata: DocsMetadata;
    }>;
    /**
     * Get all items without date filtering
     */
    getItems(options?: RequestOptions): Promise<{
        data: ItemsStatusData;
        metadata: ItemsStatusMetadata;
    }>;
    /**
     * Get all item groups
     *
     * Retrieves all item groups from the SAP HANA database with their codes and names.
     * Item groups provide categorization information for inventory items.
     *
     * @param {RequestOptions} [options] - Optional request configuration
     * @returns {Promise<{data: ItemGroupsData, metadata: ItemGroupsMetadata}>} Item groups with metadata
     *
     * @example
     * ```typescript
     * const response = await client.getItemGroups();
     * console.log(`Found ${response.metadata.count} item groups`);
     * response.data.groups.forEach(group => {
     *   console.log(`${group.code}: ${group.name}`);
     * });
     * ```
     */
    getItemGroups(options?: RequestOptions): Promise<{
        data: ItemGroupsData;
        metadata: ItemGroupsMetadata;
    }>;
    /**
     * Get sales data within a date range
     */
    getSales(params: SalesParams, options?: RequestOptions): Promise<{
        data: SalesData;
        metadata: SalesMetadata;
    }>;
    /**
     * Get all item hierarchies
     */
    getItemHierarchies(options?: RequestOptions): Promise<{
        data: HierarchiesData;
        metadata: HierarchiesMetadata;
    }>;
    /**
     * Get raw tree relationships (parent-child-quantity)
     */
    getItemTrees(options?: RequestOptions): Promise<{
        data: TreesData;
        metadata: TreesMetadata;
    }>;
    /**
     * Get all production sectors
     */
    getProductionSectors(options?: RequestOptions): Promise<{
        data: ProductionSectorsData;
        metadata: ProductionSectorsMetadata;
    }>;
    /**
     * Get all production plans
     */
    getPlans(options?: RequestOptions): Promise<{
        data: PlansData;
        metadata: PlansMetadata;
    }>;
    /**
     * Get a specific production plan by ID
     */
    getPlan(planId: number | string, options?: RequestOptions): Promise<{
        data: SinglePlanData;
        metadata: SinglePlanMetadata;
    }>;
    /**
     * Get products for a specific production plan
     *
     * @param planId - The plan ID to get products for
     * @param options - Optional request configuration
     * @returns Promise resolving to plan products data and metadata
     *
     * @throws {NotFoundError} When the plan with the specified ID doesn't exist (HTTP 404)
     * @throws {ValidationError} When the planId parameter is invalid (HTTP 400)
     * @throws {AuthorizationError} When the request is not authorized (HTTP 401/403)
     * @throws {HanaQueryClientError} For other client or server errors
     *
     * @example
     * ```typescript
     * try {
     *   const result = await client.getPlanProducts(123);
     *   if (result.data.products.length === 0) {
     *     console.log('Plan exists but has no products');
     *   } else {
     *     console.log(`Found ${result.data.products.length} products`);
     *   }
     * } catch (error) {
     *   if (error instanceof NotFoundError) {
     *     console.log('Plan does not exist');
     *   } else {
     *     console.log('Other error:', error.message);
     *   }
     * }
     * ```
     *
     * @remarks
     * - Returns HTTP 200 with empty array when plan exists but has no products
     * - Returns HTTP 404 only when the plan itself doesn't exist
     * - Empty products array is a normal, successful response
     */
    getPlanProducts(planId: number | string, options?: RequestOptions): Promise<{
        data: PlanProductsData;
        metadata: PlanProductsMetadata;
    }>;
    /**
     * Get work orders for a specific production plan
     *
     * @param planId - The plan ID to get work orders for
     * @param options - Optional request configuration
     * @returns Promise resolving to plan work orders data and metadata
     *
     * @throws {NotFoundError} When the plan with the specified ID doesn't exist (HTTP 404)
     * @throws {ValidationError} When the planId parameter is invalid (HTTP 400)
     * @throws {AuthorizationError} When the request is not authorized (HTTP 401/403)
     * @throws {HanaQueryClientError} For other client or server errors
     *
     * @example
     * ```typescript
     * try {
     *   const result = await client.getPlanWorkOrders(123);
     *   if (result.data.workOrders.length === 0) {
     *     console.log('Plan exists but has no work orders');
     *   } else {
     *     console.log(`Found ${result.data.workOrders.length} work orders`);
     *   }
     * } catch (error) {
     *   if (error instanceof NotFoundError) {
     *     console.log('Plan does not exist');
     *   } else {
     *     console.log('Other error:', error.message);
     *   }
     * }
     * ```
     *
     * @remarks
     * - Returns HTTP 200 with empty array when plan exists but has no work orders
     * - Returns HTTP 404 only when the plan itself doesn't exist
     * - Empty work orders array is a normal, successful response
     */
    getPlanWorkOrders(planId: number | string, options?: RequestOptions): Promise<{
        data: PlanWorkOrdersData;
        metadata: PlanWorkOrdersMetadata;
    }>;
    /**
     * Get sector summaries for a specific production plan
     *
     * @param planId - The plan ID to get sector summaries for
     * @param options - Optional request configuration
     * @returns Promise resolving to plan sectors summary data and metadata
     *
     * @throws {NotFoundError} When the plan with the specified ID doesn't exist (HTTP 404)
     * @throws {ValidationError} When the planId parameter is invalid (HTTP 400)
     * @throws {AuthorizationError} When the request is not authorized (HTTP 401/403)
     * @throws {HanaQueryClientError} For other client or server errors
     *
     * @example
     * ```typescript
     * try {
     *   const result = await client.getPlanSectorsSummary(123);
     *   if (result.data.sectors.length === 0) {
     *     console.log('Plan exists but has no sectors');
     *   } else {
     *     console.log(`Found ${result.data.sectors.length} sectors`);
     *     console.log(`Completion rate: ${result.metadata.completion_rate}%`);
     *   }
     * } catch (error) {
     *   if (error instanceof NotFoundError) {
     *     console.log('Plan does not exist');
     *   } else {
     *     console.log('Other error:', error.message);
     *   }
     * }
     * ```
     *
     * @remarks
     * - Returns HTTP 200 with empty array when plan exists but has no sectors
     * - Returns HTTP 404 only when the plan itself doesn't exist
     * - Empty sectors array is a normal, successful response
     * - Metadata includes aggregated statistics (total planned, completed, completion rate)
     */
    getPlanSectorsSummary(planId: number | string, options?: RequestOptions): Promise<{
        data: PlanSectorsSummaryData;
        metadata: PlanSectorsSummaryMetadata;
    }>;
    /**
     * Get sector summaries for all production plans
     *
     * @param options - Optional request configuration
     * @returns Promise resolving to all plans sectors summary data and metadata
     *
     * @throws {ValidationError} When the request parameters are invalid (HTTP 400)
     * @throws {AuthorizationError} When the request is not authorized (HTTP 401/403)
     * @throws {HanaQueryClientError} For other client or server errors
     *
     * @example
     * ```typescript
     * const result = await client.getAllPlansSectorsSummary();
     * console.log(`Found ${result.data.sectors.length} total sectors`);
     * console.log(`Across ${result.metadata.unique_plans} unique plans`);
     * console.log(`Overall completion rate: ${result.metadata.overall_completion_rate}%`);
     *
     * // Group sectors by plan
     * const sectorsByPlan = result.data.sectors.reduce((acc, sector) => {
     *   if (!acc[sector.plan_entry]) acc[sector.plan_entry] = [];
     *   acc[sector.plan_entry].push(sector);
     *   return acc;
     * }, {} as Record<number, PlanSectorSummary[]>);
     * ```
     *
     * @remarks
     * - Returns all sector summaries across all plans in the system
     * - Empty array indicates no sectors exist in any plan
     * - Metadata includes overall statistics and unique counts
     */
    getAllPlansSectorsSummary(options?: RequestOptions): Promise<{
        data: AllPlansSectorsSummaryData;
        metadata: AllPlansSectorsSummaryMetadata;
    }>;
    /**
     * Get user by username
     */
    getUser(username: string, options?: RequestOptions): Promise<{
        data: UserData;
        metadata: UserMetadata;
    }>;
    /**
     * Check if a plan exists without fetching its full details
     *
     * @param planId - The plan ID to check
     * @param options - Optional request configuration
     * @returns Promise resolving to true if plan exists, false otherwise
     *
     * @example
     * ```typescript
     * const exists = await client.planExists(123);
     * if (exists) {
     *   console.log('Plan exists');
     * } else {
     *   console.log('Plan not found');
     * }
     * ```
     */
    planExists(planId: number | string, options?: RequestOptions): Promise<boolean>;
    /**
     * Get plan products with explicit plan existence information
     *
     * @param planId - The plan ID to get products for
     * @param options - Optional request configuration
     * @returns Promise resolving to plan existence status, products, and metadata
     *
     * @example
     * ```typescript
     * const result = await client.getPlanProductsSafe(123);
     * if (!result.planExists) {
     *   console.log('Plan does not exist');
     * } else if (result.products.length === 0) {
     *   console.log('Plan exists but has no products');
     * } else {
     *   console.log(`Plan has ${result.products.length} products`);
     * }
     * ```
     */
    getPlanProductsSafe(planId: number | string, options?: RequestOptions): Promise<{
        planExists: boolean;
        products: PlanProductsData['products'];
        metadata: PlanProductsMetadata;
    }>;
    /**
     * Get plan work orders with explicit plan existence information
     *
     * @param planId - The plan ID to get work orders for
     * @param options - Optional request configuration
     * @returns Promise resolving to plan existence status, work orders, and metadata
     *
     * @example
     * ```typescript
     * const result = await client.getPlanWorkOrdersSafe(123);
     * if (!result.planExists) {
     *   console.log('Plan does not exist');
     * } else if (result.workOrders.length === 0) {
     *   console.log('Plan exists but has no work orders');
     * } else {
     *   console.log(`Plan has ${result.workOrders.length} work orders`);
     * }
     * ```
     */
    getPlanWorkOrdersSafe(planId: number | string, options?: RequestOptions): Promise<{
        planExists: boolean;
        workOrders: PlanWorkOrdersData['workOrders'];
        metadata: PlanWorkOrdersMetadata;
    }>;
    /**
     * Create a request builder for fluent API usage
     */
    request(endpoint: string): RequestBuilder;
    /**
     * Core request method with retry logic and error handling
     */
    private executeAPIRequest;
    /**
     * Execute a single HTTP request
     */
    private executeRequest;
    /**
     * Parse response headers into typed object
     */
    private parseResponseHeaders;
    /**
     * Check authorization status from headers
     */
    private checkAuthorization;
    /**
     * Sleep for specified milliseconds
     */
    private sleep;
    /**
     * Logging method
     */
    private log;
    /**
     * Get current client configuration
     */
    getConfig(): Readonly<Required<ClientConfig>>;
    /**
     * Update client configuration
     */
    updateConfig(updates: Partial<ClientConfig>): void;
    /**
     * Test connection to the API
     */
    testConnection(): Promise<boolean>;
}
/**
 * Request Builder for fluent API usage
 */
export declare class RequestBuilder {
    private client;
    private endpoint;
    private params;
    private requestOptions;
    constructor(client: HanaQueryClient, endpoint: string);
    /**
     * Add query parameters
     */
    query(params: Record<string, any>): this;
    /**
     * Set request timeout
     */
    timeout(ms: number): this;
    /**
     * Set retry count
     */
    retries(count: number): this;
    /**
     * Set abort signal
     */
    signal(signal: AbortSignal): this;
    /**
     * Execute the request
     */
    execute<T extends APIResponse>(): Promise<T>;
}
/**
 * Factory function to create a client instance
 */
export declare function createClient(config: ClientConfig, customConfig?: Partial<Omit<ClientConfig, 'baseUrl'>>): HanaQueryClient;
/**
 * Factory function to create a client from environment configuration
 */
export declare function createClientFromEnvironment(environment: string, customConfig?: Partial<ClientConfig>): HanaQueryClient;
/**
 * Default client instance (requires baseUrl to be set via environment or manual configuration)
 * Example: createClient({ baseUrl: 'http://localhost:3001' })
 */
//# sourceMappingURL=hana-query-client.d.ts.map