import Koa, { Context, Middleware } from "koa";

//#region src/asyncMiddleware/asyncMiddleware.d.ts
declare namespace asyncMiddleware_d_exports {
  export { lazyLoad };
}
/**
 * Wraps an asynchronously-initialised middleware to allow it to be
 * synchronously attached to a Koa application.
 *
 * This lazy loads the function supplied through the `init` parameter at time of
 * request. If initialisation fails, the error is thrown up the chain for
 * in-flight requests, and initialisation is retried on the next request.
 * If `ttl` is set, the middleware is re-initialised when cache expires.
 *
 * @param init  - Function to asynchronously initialise a middleware
 * @param ttl - Time in ms
 */
declare const lazyLoad: <State, Context>(init: () => Promise<Middleware<State, Context>>, ttl?: number) => Middleware<State, Context>;
declare namespace errorMiddleware_d_exports {
  export { JsonResponse, handle, thrown };
}
/**
 * Custom error type supporting JSON response bodies
 *
 * The `handle` middleware will return either `message` or `body` depending on
 * the request's `Accept` header.
 *
 * ```javascript
 * ctx.throw(400, new JsonResponse('Invalid input', { fieldName: '/foo' }));
 * ```
 */
declare class JsonResponse extends Error {
  body: unknown;
  /**
   * The property used by `handle` to infer that this error contains a body that
   * can be exposed in the HTTP response.
   */
  isJsonResponse: true;
  /**
   * Creates a new `JsonResponse`
   *
   * This must be passed to `ctx.throw` instead of being thrown directly.
   *
   * @param message - Plain text message used for requests preferring
   *                  `text/plain`. This is also used as the `Error` superclass
   *                  message.
   *
   * @param body - JavaScript value used for requests accepting
   *               `application/json`. This is encoded as JSON in the response.
   */
  constructor(message: string, body: unknown);
}
/**
 * Catches errors thrown from downstream middleware, as specified here:
 *
 * https://github.com/koajs/koa/wiki/Error-Handling#catching-downstream-errors
 *
 * If you use `http-errors` or Koa's built-in `ctx.throw`, this tries to extract
 * a numeric error `status` to serve as the response status, and will set the
 * error message as the response body for non-5xx statuses.
 *
 * This includes support for a JSON response body by throwing an error with
 * `isJsonResponse` set to `true`. If the request accepts `application/json` the
 * error's `body` will be returned, otherwise its plain text `message`.
 *
 * This should be placed high up the middleware chain so that errors from lower
 * middleware are handled. It also serves to set the correct `ctx.status` for
 * middleware that emit logs or metrics containing the response status. For
 * this reason, we recommend a sequence like:
 *
 * ```javascript
 * app
 *   .use(requestLoggingMiddleware)
 *   .use(metricsMiddleware)
 *   .use(ErrorMiddleware.handle)
 *   .use(allTheRest);
 * ```
 */
declare const handle: Middleware;
/**
 * Retrieve the error caught by `ErrorMiddleware.handle` from state.
 *
 * This is useful if you want to do something with the error higher up in the
 * middleware chain.
 */
declare const thrown: (ctx: Context) => unknown;
//#endregion
//#region src/metricsMiddleware/statsD.d.ts
type Tags = Record<string, string> | string[];
/**
 * Vendored from `hot-shots.StatsD` so that TypeScript consumers are not forced
 * to install `hot-shots` when they are not using MetricsMiddleware.
 */
interface StatsD {
  distribution(stat: string | string[], value: number, sampleRate?: number, tags?: Tags): void;
}
declare namespace metricsMiddleware_d_exports {
  export { create$1 as create };
}
/**
 * Returns metrics tags for the passed Koa context
 *
 * Typically at least the route name should be returned. Due to the various
 * ways to perform routing in Koa there is no universal way to accomplish this.
 *
 * This is called during the response chain. This gives it access to the full
 * request and response.
 */
type TagsForContext = (ctx: Koa.Context) => Record<string, unknown> | undefined;
/**
 * Creates a new request metrics middleware
 *
 * This records a `request.distribution` metric for every request. It will have
 * `http_status` and `http_status_family` tags in addition to what's returned
 * by `tagsForContext`.
 *
 * If `skipRequestLogging` is set on the state the request will not be logged.
 *
 * This should be attached early in the middleware chain to ensure metrics can
 * be recorded for requests rejected by downstream middleware and the latency
 * is inclusive.
 *
 * @param metricsClient  - Metrics client to use for recording metrics
 * @param tagsForContext - Function to return a base set of metrics tags
 */
declare const create$1: (metricsClient: StatsD, tagsForContext: TagsForContext, sampleRate?: number) => Koa.Middleware;
declare namespace requestLogging_d_exports {
  export { ContextFields, Fields, SENSITIVE_HEADER_REPLACEMENTS, State, contextFields, createContextStorage, createMiddleware };
}
/**
 * Key-value pairs of fields to log
 */
type Fields = Record<string, unknown>;
/**
 * Defines a set of substitutions to perform on request headers
 *
 * This is typically used to mask sensitive headers. However, it can also be
 * used to omit uninteresting headers from the request log by replacing them
 * with `undefined`.
 */
type HeaderReplacements = Record<string, string | undefined>;
/**
 * Header substitutions for masking sensitive data
 *
 * These headers typically contain user credentials such as JWTs or session
 * cookies.
 */
declare const SENSITIVE_HEADER_REPLACEMENTS: HeaderReplacements;
/**
 * Koa context state extensions for request logging
 */
interface State {
  /**
   * Indicates a request shouldn't appear in the request log
   */
  skipRequestLogging?: boolean;
}
/**
 * Returns context fields for the passed Koa context
 */
type ContextFields = (ctx: Koa.Context, fields?: Fields) => Record<string, unknown>;
/**
 * Returns an object of request-specific log fields
 *
 * The returned object includes key-value pairs for the request method, route,
 * URL and tracing IDs. This can be used to construct a child logger that
 * annotates log entries with request-specific information.
 *
 * The route properties assume use of `@koa/router`, and are omitted if the
 * expected metadata is not present on context.
 *
 * @param ctx - Koa Context
 * @param fields - Optional fields to add to the object
 */
declare const contextFields: ContextFields;
/**
 * Creates middleware for logging requests and their responses
 *
 * This calls `logFn` for every response with a set of fields to be logged.
 * This will typically call the app's logger with a fixed message.
 *
 * In addition to the fields returned by `contextFields` this adds the
 * request headers, response latency, final status code. In the case of
 * uncaught exceptions it will also add the error string.
 *
 * If `skipRequestLogging` is set on the state the request will not be logged.
 *
 * This should be attached early in the request chain to ensure log entries can
 * be created for requests rejected by downstream middleware and the recorded
 * latency is inclusive.
 */
declare const createMiddleware: <StateT extends State, CustomT>(logFn: (ctx: Koa.ParameterizedContext<StateT, CustomT>, fields: Fields, error?: unknown) => void, headerReplacements?: HeaderReplacements) => Koa.Middleware<StateT, CustomT>;
declare const createContextStorage: () => {
  /**
   * Koa Middleware that injects the logger context into an AsyncLocalStorage instance
   * @param getFieldsFn - Optional function to return a set of fields to include in context. Defaults to `contextFields`
   */
  createContextMiddleware: (getFieldsFn?: ContextFields) => Koa.Middleware;
  /**
   * Returns a shallow copy of fields from the logger context store. For performance reason we only copy the surface level fields.
   */
  mixin: () => {
    [x: string]: unknown;
  };
};
declare namespace secureHeaders_d_exports {
  export { middleware };
}
/**
 * Adds HTTP response headers that opt-in to stricter browser security policies
 *
 * This middleware makes the following assumptions:
 * 1. The app's domain does not mix HTTP and HTTPS
 * 2. The response is an API response, i.e. it is not being directly rendered
 *    by the browser
 * 3. The responses have an accurate `Content-Type` header
 */
declare const middleware: Koa.Middleware;
//#endregion
//#region src/types.d.ts
/**
 * Identifies the current application
 *
 * Many apps will have a configuration object that already conforms to this.
 */
interface AppIdentifier {
  /**
   * Name of the application
   *
   * This will typically be the name of the GitHub repository
   */
  name: string;
  /**
   * Version of the application
   *
   * This will typically be a CI build number.
   */
  version?: string;
}
declare namespace tracingHeaders_d_exports {
  export { ADHOC_SESSION_ID_HEADER, EC_SESSION_ID_HEADER, EC_VISITOR_ID_HEADER, REQUEST_ID_HEADER, SEEKTracing, outgoingHeaders, tracingFromContext };
}
/** HTTP header name for the request ID */
declare const REQUEST_ID_HEADER = "x-request-id";
/** HTTP header name for the event capture session ID */
declare const EC_SESSION_ID_HEADER = "x-seek-ec-sessionid";
/** HTTP header name for the event capture visitor ID */
declare const EC_VISITOR_ID_HEADER = "x-seek-ec-visitorid";
/** HTTP header name for an ad-hoc session ID */
declare const ADHOC_SESSION_ID_HEADER = "x-session-id";
/** Encapsulates the extracted tracing from an incoming request */
interface SEEKTracing {
  /**
   * Unique identifier for a client-initiated request
   *
   * The semantics of this header is documented in SEEK RFC002.
   */
  requestID: string;
  /**
   * Optional event capture session ID
   *
   * Reflects the value of the candidate's `JobseekerSessionId` cookie.
   */
  ecSessionID?: string;
  /**
   * Optional event capture visitor ID
   *
   * Reflects the value of the candidate's `JobseekerVisitorId` cookie.
   */
  ecVisitorID?: string;
  /**
   * Optional ad-hoc session ID
   *
   * Defined contextually by the system using it.
   */
  adhocSessionID?: string;
}
/**
 * Extracts tracing information from an incoming request
 *
 * If no request ID is present one will be generated and cached on the state.
 */
declare const tracingFromContext: (ctx: Koa.Context) => SEEKTracing;
/**
 * Generates tracing headers for an outgoing request
 *
 * This sets both the SEEK tracing headers and a distinctive `User-Agent`.
 */
declare const outgoingHeaders: (appID: AppIdentifier, tracing: SEEKTracing) => Record<string, string>;
declare namespace versionMiddleware_d_exports {
  export { create };
}
/**
 * Creates a middleware for attaching app version information to responses
 *
 * This has no dependencies and can be added in any order.
 */
declare const create: (appID: AppIdentifier) => Koa.Middleware;
//#endregion
export { type AppIdentifier, asyncMiddleware_d_exports as AsyncMiddleware, errorMiddleware_d_exports as ErrorMiddleware, metricsMiddleware_d_exports as MetricsMiddleware, requestLogging_d_exports as RequestLogging, secureHeaders_d_exports as SecureHeaders, tracingHeaders_d_exports as TracingHeaders, versionMiddleware_d_exports as VersionMiddleware };
//# sourceMappingURL=index.d.mts.map