[ML] Fix types for headers. Improves some docs.

packages/kbn-aiops-utils/README.md

@@ -1,3 +1,3 @@
 # @kbn/aiops-utils
 
-Empty package generated by @kbn/generate
+The `aiops-utils` package contains static utilities maintained by the ML team for AIOps related efforts.

packages/kbn-aiops-utils/src/lib/accept_compression.ts

@@ -6,18 +6,15 @@
  * Side Public License, v 1.
  */
 
-// TODO: Replace these with kbn packaged versions once we have those available to us
-// These originally came from this location below before moving them to this hacked "any" types:
-// import type { Headers } from '@kbn/core/server';
-type Headers = Record<string, unknown>;
+import { IncomingHttpHeaders } from 'http';
 
 /**
  * Returns whether request headers accept a response using gzip compression.
  *
  * @param headers - Request headers.
  * @returns boolean
  */
-export function acceptCompression(headers: Headers) {
+export function acceptCompression(headers: IncomingHttpHeaders) {
   let compressed = false;
 
   Object.keys(headers).forEach((key) => {

packages/kbn-aiops-utils/src/lib/stream_factory.ts

@@ -8,11 +8,7 @@
 
 import { Stream } from 'stream';
 import zlib from 'zlib';
-
-// TODO: Replace these with kbn packaged versions once we have those available to us
-// These originally came from this location below before moving them to this hacked "any" types:
-// import type { Headers } from '@kbn/core/server';
-type Headers = Record<string, unknown>;
+import { IncomingHttpHeaders } from 'http';
 
 import { acceptCompression } from './accept_compression';
 
@@ -33,19 +29,28 @@ interface StreamFactoryReturnType<T = unknown> {
   push: (d: T) => void;
   responseWithHeaders: {
     body: zlib.Gzip | ResponseStream;
-    headers?: Headers;
+    headers?: IncomingHttpHeaders;
   };
 }
 
+/**
+ * Overload to set up a string based response stream with support
+ * for gzip compression depending on provided request headers.
+ *
+ * @param headers - Request headers.
+ * @returns An object with stream attributes and methods.
+ */
+export function streamFactory<T = string>(headers: IncomingHttpHeaders): StreamFactoryReturnType<T>;
 /**
  * Sets up a response stream with support for gzip compression depending on provided
  * request headers. Any non-string data pushed to the stream will be stream as NDJSON.
  *
  * @param headers - Request headers.
  * @returns An object with stream attributes and methods.
  */
-export function streamFactory<T = string>(headers: Headers): StreamFactoryReturnType<T>;
-export function streamFactory<T = unknown>(headers: Headers): StreamFactoryReturnType<T> {
+export function streamFactory<T = unknown>(
+  headers: IncomingHttpHeaders
+): StreamFactoryReturnType<T> {
   let streamType: StreamType;
   const isCompressed = acceptCompression(headers);
 

packages/kbn-aiops-utils/src/lib/use_fetch_stream.ts

@@ -20,12 +20,18 @@ import {
 import { fetchStream } from './fetch_stream';
 import { stringReducer, StringReducer } from './string_reducer';
 
+/**
+ * Custom hook type definition of the base params for an NDJSON stream with custom reducer.
+ */
 export interface UseFetchStreamCustomReducerParams {
   endpoint: string;
   body: object;
   reducer: Reducer<any, any>;
 }
 
+/**
+ * Custom hook type definition of the base params for a string base stream without a custom reducer.
+ */
 export interface UseFetchStreamParamsDefault {
   endpoint: string;
   body: object;
@@ -58,6 +64,14 @@ export function useFetchStream<
   options: { reducer: I['reducer']; initialState: ReducerState<I['reducer']> }
 ): UseFetchStreamReturnType<ReducerState<I['reducer']>, ReducerAction<I['reducer']>>;
 
+/**
+ * Custom hook to receive streaming data.
+ *
+ * @param endpoint - API endpoint including Kibana base path.
+ * @param body - API request body.
+ * @param options - Optional custom reducer and initial state.
+ * @returns An object with streaming data and methods act on the stream.
+ */
 export function useFetchStream<I extends UseFetchStreamParamsDefault, BasePath extends string>(
   endpoint: `${BasePath}${I['endpoint']}`,
   body: I['body'],