@inkeep/agents-manage-mcp 0.38.0 → 0.38.1

package/dist/index.d.ts

@@ -0,0 +1,369 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+type Fetcher = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+type Awaitable$1<T> = T | Promise<T>;
+type RequestInput = {
+    /**
+     * The URL the request will use.
+     */
+    url: URL;
+    /**
+     * Options used to create a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request).
+     */
+    options?: RequestInit | undefined;
+};
+interface HTTPClientOptions {
+    fetcher?: Fetcher;
+}
+type BeforeRequestHook$1 = (req: Request) => Awaitable$1<Request | void>;
+type RequestErrorHook = (err: unknown, req: Request) => Awaitable$1<void>;
+type ResponseHook = (res: Response, req: Request) => Awaitable$1<void>;
+declare class HTTPClient {
+    private options;
+    private fetcher;
+    private requestHooks;
+    private requestErrorHooks;
+    private responseHooks;
+    constructor(options?: HTTPClientOptions);
+    request(request: Request): Promise<Response>;
+    /**
+     * Registers a hook that is called before a request is made. The hook function
+     * can mutate the request or return a new request. This may be useful to add
+     * additional information to request such as request IDs and tracing headers.
+     */
+    addHook(hook: 'beforeRequest', fn: BeforeRequestHook$1): this;
+    /**
+     * Registers a hook that is called when a request cannot be made due to a
+     * network error.
+     */
+    addHook(hook: 'requestError', fn: RequestErrorHook): this;
+    /**
+     * Registers a hook that is called when a response has been received from the
+     * server.
+     */
+    addHook(hook: 'response', fn: ResponseHook): this;
+    /** Removes a hook that was previously registered with `addHook`. */
+    removeHook(hook: 'beforeRequest', fn: BeforeRequestHook$1): this;
+    /** Removes a hook that was previously registered with `addHook`. */
+    removeHook(hook: 'requestError', fn: RequestErrorHook): this;
+    /** Removes a hook that was previously registered with `addHook`. */
+    removeHook(hook: 'response', fn: ResponseHook): this;
+    clone(): HTTPClient;
+}
+
+interface Logger {
+    group(label?: string): void;
+    groupEnd(): void;
+    log(message: any, ...args: any[]): void;
+}
+
+type BackoffStrategy = {
+    initialInterval: number;
+    maxInterval: number;
+    exponent: number;
+    maxElapsedTime: number;
+};
+type RetryConfig = {
+    strategy: 'none';
+} | {
+    strategy: 'backoff';
+    backoff?: BackoffStrategy;
+    retryConnectionErrors?: boolean;
+};
+
+type SDKOptions = {
+    httpClient?: HTTPClient;
+    /**
+     * Allows overriding the default server used by the SDK
+     */
+    serverIdx?: number | undefined;
+    /**
+     * Allows overriding the default server URL used by the SDK
+     */
+    serverURL?: string | undefined;
+    /**
+     * Allows overriding the default user agent used by the SDK
+     */
+    userAgent?: string | undefined;
+    /**
+     * Allows overriding the default retry config used by the SDK
+     */
+    retryConfig?: RetryConfig;
+    timeoutMs?: number;
+    debugLogger?: Logger | undefined;
+};
+
+type OAuth2PasswordFlow = {
+    username: string;
+    password: string;
+    clientID?: string | undefined;
+    clientSecret?: string | undefined;
+    tokenURL: string;
+};
+type SecurityState = {
+    basic: {
+        username?: string | undefined;
+        password?: string | undefined;
+    };
+    headers: Record<string, string>;
+    queryParams: Record<string, string>;
+    cookies: Record<string, string>;
+    oauth2: ({
+        type: 'password';
+    } & OAuth2PasswordFlow) | {
+        type: 'none';
+    };
+};
+
+type HookContext = {
+    baseURL: string | URL;
+    operationID: string;
+    oAuth2Scopes: string[] | null;
+    securitySource?: any | (() => Promise<any>);
+    retryConfig: RetryConfig;
+    resolvedSecurity: SecurityState | null;
+    options: SDKOptions;
+};
+type Awaitable<T> = T | Promise<T>;
+type BeforeCreateRequestContext = HookContext & {};
+type BeforeRequestContext = HookContext & {};
+type AfterSuccessContext = HookContext & {};
+type AfterErrorContext = HookContext & {};
+/**
+ * SDKInitHook is called when the SDK is initializing. The
+ * hook can return a new baseURL and HTTP client to be used by the SDK.
+ */
+interface SDKInitHook {
+    sdkInit: (opts: SDKOptions) => SDKOptions;
+}
+interface BeforeCreateRequestHook {
+    /**
+     * A hook that is called before the SDK creates a `Request` object. The hook
+     * can modify how a request is constructed since certain modifications, like
+     * changing the request URL, cannot be done on a request object directly.
+     */
+    beforeCreateRequest: (hookCtx: BeforeCreateRequestContext, input: RequestInput) => RequestInput;
+}
+interface BeforeRequestHook {
+    /**
+     * A hook that is called before the SDK sends a request. The hook can
+     * introduce instrumentation code such as logging, tracing and metrics or
+     * replace the request before it is sent or throw an error to stop the
+     * request from being sent.
+     */
+    beforeRequest: (hookCtx: BeforeRequestContext, request: Request) => Awaitable<Request>;
+}
+interface AfterSuccessHook {
+    /**
+     * A hook that is called after the SDK receives a response. The hook can
+     * introduce instrumentation code such as logging, tracing and metrics or
+     * modify the response before it is handled or throw an error to stop the
+     * response from being handled.
+     */
+    afterSuccess: (hookCtx: AfterSuccessContext, response: Response) => Awaitable<Response>;
+}
+interface AfterErrorHook {
+    /**
+     * A hook that is called after the SDK encounters an error, or a
+     * non-successful response. The hook can introduce instrumentation code such
+     * as logging, tracing and metrics or modify the response or error values.
+     */
+    afterError: (hookCtx: AfterErrorContext, response: Response | null, error: unknown) => Awaitable<{
+        response: Response | null;
+        error: unknown;
+    }>;
+}
+interface Hooks {
+    /** Registers a hook to be used by the SDK for initialization event. */
+    registerSDKInitHook(hook: SDKInitHook): void;
+    /** Registers a hook to be used by the SDK for to modify `Request` construction. */
+    registerBeforeCreateRequestHook(hook: BeforeCreateRequestHook): void;
+    /** Registers a hook to be used by the SDK for the before request event. */
+    registerBeforeRequestHook(hook: BeforeRequestHook): void;
+    /** Registers a hook to be used by the SDK for the after success event. */
+    registerAfterSuccessHook(hook: AfterSuccessHook): void;
+    /** Registers a hook to be used by the SDK for the after error event. */
+    registerAfterErrorHook(hook: AfterErrorHook): void;
+}
+
+declare class SDKHooks implements Hooks {
+    sdkInitHooks: SDKInitHook[];
+    beforeCreateRequestHooks: BeforeCreateRequestHook[];
+    beforeRequestHooks: BeforeRequestHook[];
+    afterSuccessHooks: AfterSuccessHook[];
+    afterErrorHooks: AfterErrorHook[];
+    constructor();
+    registerSDKInitHook(hook: SDKInitHook): void;
+    registerBeforeCreateRequestHook(hook: BeforeCreateRequestHook): void;
+    registerBeforeRequestHook(hook: BeforeRequestHook): void;
+    registerAfterSuccessHook(hook: AfterSuccessHook): void;
+    registerAfterErrorHook(hook: AfterErrorHook): void;
+    sdkInit(opts: SDKOptions): SDKOptions;
+    beforeCreateRequest(hookCtx: BeforeCreateRequestContext, input: RequestInput): RequestInput;
+    beforeRequest(hookCtx: BeforeRequestContext, request: Request): Promise<Request>;
+    afterSuccess(hookCtx: AfterSuccessContext, response: Response): Promise<Response>;
+    afterError(hookCtx: AfterErrorContext, response: Response | null, error: unknown): Promise<{
+        response: Response | null;
+        error: unknown;
+    }>;
+}
+
+/**
+ * Base class for all HTTP errors.
+ */
+declare class HTTPClientError extends Error {
+    /** The underlying cause of the error. */
+    readonly cause: unknown;
+    name: string;
+    constructor(message: string, opts?: {
+        cause?: unknown;
+    });
+}
+/**
+ * An error to capture unrecognised or unexpected errors when making HTTP calls.
+ */
+declare class UnexpectedClientError extends HTTPClientError {
+    name: string;
+}
+/**
+ * An error that is raised when any inputs used to create a request are invalid.
+ */
+declare class InvalidRequestError extends HTTPClientError {
+    name: string;
+}
+/**
+ * An error that is raised when a HTTP request was aborted by the client error.
+ */
+declare class RequestAbortedError extends HTTPClientError {
+    readonly name = "RequestAbortedError";
+}
+/**
+ * An error that is raised when a HTTP request timed out due to an AbortSignal
+ * signal timeout.
+ */
+declare class RequestTimeoutError extends HTTPClientError {
+    readonly name = "RequestTimeoutError";
+}
+/**
+ * An error that is raised when a HTTP client is unable to make a request to
+ * a server.
+ */
+declare class ConnectionError extends HTTPClientError {
+    readonly name = "ConnectionError";
+}
+
+/**
+ * A monad that captures the result of a function call or an error if it was not
+ * successful. Railway programming, enabled by this type, can be a nicer
+ * alternative to traditional exception throwing because it allows functions to
+ * declare all _known_ errors with static types and then check for them
+ * exhaustively in application code. Thrown exception have a type of `unknown`
+ * and break out of regular control flow of programs making them harder to
+ * inspect and more verbose work with due to try-catch blocks.
+ */
+type Result<T, E = unknown> = {
+    ok: true;
+    value: T;
+    error?: never;
+} | {
+    ok: false;
+    value?: never;
+    error: E;
+};
+
+type RequestOptions = {
+    /**
+     * Sets a timeout, in milliseconds, on HTTP requests made by an SDK method. If
+     * `fetchOptions.signal` is set then it will take precedence over this option.
+     */
+    timeoutMs?: number;
+    /**
+     * Set or override a retry policy on HTTP calls.
+     */
+    retries?: RetryConfig;
+    /**
+     * Specifies the status codes which should be retried using the given retry policy.
+     */
+    retryCodes?: string[];
+    /**
+     * Overrides the base server URL that will be used by an operation.
+     */
+    serverURL?: string | URL;
+    /**
+     * @deprecated `fetchOptions` has been flattened into `RequestOptions`.
+     *
+     * Sets various request options on the `fetch` call made by an SDK method.
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options|Request}
+     */
+    fetchOptions?: Omit<RequestInit, 'method' | 'body'>;
+} & Omit<RequestInit, 'method' | 'body'>;
+type RequestConfig = {
+    method: string;
+    path: string;
+    baseURL?: string | URL | undefined;
+    query?: string;
+    body?: RequestInit['body'];
+    headers?: HeadersInit;
+    security?: SecurityState | null;
+    uaHeader?: string;
+    userAgent?: string | undefined;
+    timeoutMs?: number;
+};
+declare class ClientSDK {
+    #private;
+    readonly _baseURL: URL | null;
+    readonly _options: SDKOptions & {
+        hooks?: SDKHooks;
+    };
+    constructor(options?: SDKOptions);
+    _createRequest(context: HookContext, conf: RequestConfig, options?: RequestOptions): Result<Request, InvalidRequestError | UnexpectedClientError>;
+    _do(request: Request, options: {
+        context: HookContext;
+        errorCodes: number | string | (number | string)[];
+        retryConfig: RetryConfig;
+        retryCodes: string[];
+    }): Promise<Result<Response, RequestAbortedError | RequestTimeoutError | ConnectionError | UnexpectedClientError>>;
+}
+
+/**
+ * A minimal client to use when calling standalone SDK functions. Typically, an
+ * instance of this class would be instantiated once at the start of an
+ * application and passed around through some dependency injection mechanism  to
+ * parts of an application that need to make SDK calls.
+ */
+declare class InkeepAgentsCore extends ClientSDK {
+}
+
+/**
+ * HeaderForwardingHook forwards specified headers from incoming requests to outgoing SDK requests.
+ * Used to propagate authentication headers (like cookies) through the MCP server to the downstream API.
+ */
+declare class HeaderForwardingHook implements BeforeRequestHook {
+    private headersToForward;
+    constructor(headersToForward: Record<string, string>);
+    beforeRequest(_hookCtx: BeforeRequestContext, request: Request): Promise<Request>;
+}
+
+declare const consoleLoggerLevels: readonly ["debug", "warning", "info", "error"];
+type ConsoleLoggerLevel = (typeof consoleLoggerLevels)[number];
+type ConsoleLogger = {
+    [key in ConsoleLoggerLevel]: (message: string, data?: Record<string, unknown>) => void;
+} & {
+    level: ConsoleLoggerLevel;
+};
+declare function createConsoleLogger(level: ConsoleLoggerLevel): ConsoleLogger;
+
+declare const mcpScopes: readonly [];
+type MCPScope = (typeof mcpScopes)[number];
+
+declare function createMCPServer(deps: {
+    logger: ConsoleLogger;
+    allowedTools?: string[] | undefined;
+    scopes?: MCPScope[] | undefined;
+    getSDK?: () => InkeepAgentsCore;
+    serverURL?: string | undefined;
+    serverIdx?: SDKOptions['serverIdx'] | undefined;
+}): McpServer;
+
+export { type BeforeCreateRequestContext, type BeforeCreateRequestHook, type BeforeRequestContext, type BeforeRequestHook, type ConsoleLogger, type ConsoleLoggerLevel, HeaderForwardingHook, InkeepAgentsCore, SDKHooks, type SDKOptions, createConsoleLogger, createMCPServer };