npm package: @microsoft/kiota
Description: npm package exposing Kiota CLI functionality to TypeScript
Author: Microsoft
Latest version: 1.31.0

# @microsoft/kiota

This library provides various functions to interact with Kiota, a client generator for HTTP REST APIs described by OpenAPI.

## Installation

To install the package, use the following command:

```bash
npm install @microsoft/kiota
```

## Usage

Once installed, you can use the available functions to generate and interact with Kiota clients.
Below is a reference for each function, including parameters and return values.

### `generateClient`

Generates a client based on the provided client generation options.

**Parameters:**

- `clientGenerationOptions`: *ClientGenerationOptions* - The options for generating the client.
* Options for generating a client.
- `clientGenerationOptions.openAPIFilePath`: *string* - The file path to the OpenAPI specification.
- `clientGenerationOptions.clientClassName`: *string* - The name of the client class to generate.
- `clientGenerationOptions.clientNamespaceName`: *string* - The namespace name for the generated client.
- `clientGenerationOptions.language`: *KiotaGenerationLanguage* - The programming language for the generated client.
- `clientGenerationOptions.outputPath`: *string* - The output path for the generated client.
- `clientGenerationOptions.operation`: *ConsumerOperation* - The consumer operation to perform.
- `clientGenerationOptions.workingDirectory`: *string* - The working directory for the generation process.

- `clientGenerationOptions.clearCache` (optional): *boolean* - Whether to clear the cache before generating the client.
- `clientGenerationOptions.cleanOutput` (optional): *boolean* - Whether to clean the output directory before generating the client.
- `clientGenerationOptions.deserializers` (optional): *string[]* - The list of deserializers to use.
- `clientGenerationOptions.disabledValidationRules` (optional): *string[]* - The list of validation rules to disable.
- `clientGenerationOptions.excludeBackwardCompatible` (optional): *boolean* - Whether to exclude backward-compatible changes.
- `clientGenerationOptions.excludePatterns` (optional): *string[]* - The list of patterns to exclude from generation.
- `clientGenerationOptions.includeAdditionalData` (optional): *boolean* - Whether to include additional data in the generated client.
- `clientGenerationOptions.includePatterns` (optional): *string[]* - The list of patterns to include in generation.
- `clientGenerationOptions.serializers` (optional): *string[]* - The list of serializers to use.
- `clientGenerationOptions.structuredMimeTypes` (optional): *string[]* - The list of structured MIME types to support.
- `clientGenerationOptions.usesBackingStore` (optional): *boolean* - Whether the generated client uses a backing store.

**Returns:** A promise that resolves to a KiotaResult if successful, or undefined if not.

**Throws:**
- If an error occurs during the client generation process.

### `generatePlugin`

Generates a plugin based on the provided options.

**Parameters:**

- `pluginGenerationOptions`: *PluginGenerationOptions* - The options for generating the plugin.
- `pluginGenerationOptions.openAPIFilePath`: *string* - The file path to the OpenAPI specification.
- `pluginGenerationOptions.pluginName`: *string* - The name of the plugin to generate.
- `pluginGenerationOptions.outputPath`: *string* - The output path where the generated plugin will be saved.
- `pluginGenerationOptions.operation`: *ConsumerOperation* - The operation to perform during generation.
- `pluginGenerationOptions.workingDirectory`: *string* - The working directory for the generation process.

- `pluginGenerationOptions.pluginType` (optional): *KiotaPluginType* - The type of the plugin to generate.
- `pluginGenerationOptions.includePatterns` (optional): *string[]* - The patterns to include in the generation process.
- `pluginGenerationOptions.excludePatterns` (optional): *string[]* - The patterns to exclude from the generation process.
- `pluginGenerationOptions.clearCache` (optional): *boolean* - Whether to clear the cache before generation.
- `pluginGenerationOptions.cleanOutput` (optional): *boolean* - Whether to clean the output directory before generation.
- `pluginGenerationOptions.disabledValidationRules` (optional): *string[]* - The validation rules to disable during generation.
- `pluginGenerationOptions.pluginAuthType` (optional): *PluginAuthType | null* - The authentication type for the plugin, if any.
- `pluginGenerationOptions.pluginAuthRefid` (optional): *string* - The reference ID for the plugin authentication, if any.

**Returns:** A promise that resolves to a KiotaResult if successful, or undefined if not.

**Throws:**
- If an error occurs during the generation process.

The function connects to Kiota and sends a request to generate a plugin using the provided options.
It handles the response and checks for success, returning the result or throwing an error if one occurs.

### `getKiotaTree`

Shows the Kiota result based on the provided options.

**Parameters:**

- `options`: *KiotaResultOptions* - The options to configure the Kiota result.
- `options.descriptionPath`: *string* - The path to the description file.

- `options.includeFilters` (optional): *string[]* - Filters to include in the result.
- `options.excludeFilters` (optional): *string[]* - Filters to exclude from the result.
- `options.clearCache` (optional): *boolean* - Whether to clear the cache before showing the result.
- `options.includeKiotaValidationRules` (optional): *boolean* - Whether to evaluate built-in kiota rules when parsing the description file.

**Returns:** A promise that resolves to the Kiota show result or undefined if an error occurs.

**Throws:**
- Throws an error if the result is an instance of Error.

### `getKiotaVersion`

Retrieves the version of Kiota by connecting to the Kiota service.

**Returns:** A promise that resolves to the Kiota version string if available, otherwise undefined.

**Throws:**
- If an error occurs while connecting to the Kiota service or retrieving the version.

### `getManifestDetails`

Retrieves the manifest details for a given API.

**Parameters:**

- `options`: *ManifestOptions* - The options for retrieving the manifest details.
- `options.manifestPath`: *string* - The path to the manifest file.

- `options.clearCache` (optional): *boolean* - Whether to clear the cache before retrieving the manifest details.
- `options.apiIdentifier` (optional): *string* - The identifier of the API.

**Returns:** A promise that resolves to the manifest details or undefined if not found.

**Throws:**
- Throws an error if the request fails.

### `getPluginManifest`

Shows the Kiota result based on the provided options.

**Parameters:**

- `options`: *KiotaResultOptions* - The options to configure the Kiota result.
- `options.descriptionPath`: *string* - The path to the manifest file.

**Returns:** A promise that resolves to the result or undefined if an error occurs.

**Throws:**
- Throws an error if the result is an instance of Error.

### `getLanguageInformationInternal`

Retrieves language information by connecting to Kiota.

This function establishes a connection to Kiota and sends a request to retrieve
language information. If the request is successful, it returns the language information.
If an error occurs during the request, the error is thrown.

**Returns:** A promise that resolves to the language information or undefined if an error occurs.

**Throws:**
- Throws an error if the request fails.

### `getLanguageInformationForDescription`

Retrieves language information based on the provided description URL.

**Parameters:**

- `config`: *LanguageInformationConfiguration* - The configuration object containing the description URL and cache clearing option.
- `config.descriptionUrl`: *string* - The URL of the description to retrieve language information for.
- `config.clearCache`: *boolean* - A flag indicating whether to clear the cache before retrieving the information.

**Returns:** A promise that resolves to the language information or undefined if an error occurs.

**Throws:**
- Throws an error if the request fails.

### `migrateFromLockFile`

Migrates data from a lock file located in the specified directory.

This function connects to the Kiota service and sends a request to migrate data from the lock file.
If the migration is successful, it returns an array of `KiotaLogEntry` objects.
If an error occurs during the migration, the error is thrown.

**Parameters:**

- `lockFileDirectory`: *string* - The directory where the lock file is located.

**Returns:** A promise that resolves to an array of `KiotaLogEntry` objects if the migration is successful, or `undefined` if no data is migrated.

**Throws:**
- If an error occurs during the migration process.

### `removePlugin`

Removes a plugin from the Kiota environment.

**Parameters:**

- `config`: *RemovePluginConfiguration* - The configuration for removing the plugin.
- `config.pluginName`: *string* - The name of the plugin to remove.
- `config.cleanOutput`: *boolean* - Whether to clean the output directory after removal.
- `config.workingDirectory`: *string* - The working directory where the operation should be performed.

**Returns:** A promise that resolves to a KiotaResult if the operation is successful, or undefined if no result is returned.

**Throws:**
- Throws an error if the operation fails.

### `removeClient`

Removes a client using the provided configuration.

**Parameters:**

- `config`: *RemoveClientConfiguration* - The configuration for removing the client.
- `config.clientName`: *string* - The name of the client to be removed.
- `config.cleanOutput`: *boolean* - A flag indicating whether to clean the output.
- `config.workingDirectory`: *string* - The working directory for the operation.

**Returns:** A promise that resolves to a KiotaResult if the client was removed successfully, or undefined if no result is returned.

**Throws:**
- Throws an error if the result is an instance of Error.

### `searchDescription`

Searches for a description based on the provided search term and cache settings.

**Parameters:**

- `config`: *SearchConfiguration* - The search configuration object.
- `config.searchTerm`: *string* - The term to search for.
- `config.clearCache`: *boolean* - Whether to clear the cache before searching.

**Returns:** A promise that resolves to a record of search results or undefined if no results are found.

**Throws:**
- Throws an error if the search operation fails.

### `updateClients`

Updates the clients by connecting to Kiota and sending a request to update.

**Parameters:**

- `config`: *UpdateClientsConfiguration* - The configuration object containing the following properties:
- `config.cleanOutput`: *boolean* - Whether to clean the output directory before updating.
- `config.clearCache`: *boolean* - Whether to clear the cache before updating.
- `config.workspacePath`: *string* - The path to the workspace where the clients are located.

**Returns:** A promise that resolves to an array of Kiota log entries if the update is successful, or undefined if there is an error.

**Throws:**
- Throws an error if the result of the update is an instance of Error.