<!-- thumbnail: https://i.sstatic.net/vwxj6.png -->
<!-- version: 3.3.0 -->
<!-- tag: library -->
<!-- excerpt: Stack Exchange API Types adds type definitions for various API types  -->

## Screenshot / Code Snippet

[![animated example][1]][1]

Usage example:

```typescript
import {
    CommonWrapperObject,
    Errors,
    Filters,
    Tag,
} from "@userscripters/stackexchange-api-types";

export const getTagsAPI = async (search: string): Promise<Tag[]> => {
    const filter: Filters.BuiltIn = "default";

    const uri = new URL(`https://api.stackexchange.com/2.3/tags`);
    uri.search = new URLSearchParams({
        site: location.hostname,
        inname: search.toLowerCase(),
        filter,
    }).toString();

    const res = await fetch(uri.toString());
    if (!res.ok) return [];

    const body = await res.json();

    const { items, error_name } = body as CommonWrapperObject<Tag>;

    const errorMap: Map<Errors.Name, string> = new Map([
        ["bad_parameter", "Invalid parameter"],
        ["access_denied", "The API refused access"],
    ]);

    console.log(errorMap.get(error_name as Errors.Name));

    return items;
};
```

## About

Stack Exchange API types is a type declaration package adding type definitions for objects exposed by Stack Exchange API for both client- and server-side consumption.

The package is automatically generated, so all currently available types should be present in the definitions - do let us know if we missed anything!

### License

The package is licensed under the [GPL-3.0-or-later][2] license.

### Download

The package is published as both an [NPM package][3] and a [GitHub package][4]. Can be installed via a package manager like NPM as usual:

```shell
npm install --save-dev @userscripters/stackexchange-api-types
```

If you opt to install it from the GitHub registry, please note that it only supports scoped packages, you will need a simple .npmrc file at your project root:

```npmrc
@userscripters:registry=https://npm.pkg.github.com
```

You will also need to be logged in to GitHub. An easy way to do so is to have a global `.npmrc` with your PAT ([personal access token][2]) set as an access token:

```npmrc
//npm.pkg.github.com/:_authToken=<your token here>
```

### Platform

The type declarations are intended to be used with TypeScript/JavaScript projects targeting either browsers or server-side environments like Node.js.

## Changelog

| Version | Changes | 
| - | - |
| [0.3.0](https://github.com/userscripters/stackexchange-api-types/packages/996732?version=0.3.0) | Deduplicated generated interfaces & exported types globally as `StackExchangeAPI` namespace |
| [1.0.0](https://github.com/userscripters/stackexchange-api-types/packages/996732?version=1.0.0) | Fixed type `date` from the API being incorrectly interpreted as `Date` (it is a `number`) |
| [2.0.0](https://github.com/userscripters/stackexchange-api-types/packages/996732?version=2.0.0) | ["may be absent"][5] fields are now considered optional interface members. This makes the types more accurate but might be a breaking change for your codebase |
| [3.1.1](https://github.com/userscripters/stackexchange-api-types/packages/996732?version=3.1.1) | [Common Wrapper Object][6] that the API sends the responses wrapped into is added to the list of generated types. The interface accepts a generic type parameter for the `items` array values |
| [3.2.4](https://github.com/userscripters/stackexchange-api-types/packages/996732?version=3.2.4) | [Built-in filters][7] (e.g. `default` or `total`) string union grouped under `Filters` namespace |
| [3.3.0](https://github.com/userscripters/stackexchange-api-types/packages/996732?version=3.3.0) | [API errors][8] as `Name` and `Code` unions grouped under `Errors` namespace |

## Contact

Author: [Oleg Valter][9]<br>
Organization: [UserScripters][10]

Please, submit bug reports on the [source repository][11].
<br>Before adding a new one, please check if it hasn't been raised before.

You can also [drop by to chat][12], we are a friendly bunch.

## Code

[Source code][13] is written TypeScript (`d.ts` declaration files and type generator in proper TypeScript).

The project is using `tsd` (see [repo][14]) for unit-testing types.

Contributions are welcome, you can always submit a [PR here][15].


  [1]: https://i.sstatic.net/hgFLL.gif
  [2]: https://spdx.org/licenses/GPL-3.0-or-later
  [3]: https://www.npmjs.com/package/@userscripters/stackexchange-api-types
  [4]: https://github.com/userscripters/stackexchange-api-types/packages/996732
  [5]: https://api.stackexchange.com/docs/absent-fields
  [6]: https://api.stackexchange.com/docs/wrapper
  [7]: https://api.stackexchange.com/docs/filters
  [8]: https://api.stackexchange.com/docs/error-handling
  [9]: https://stackoverflow.com/users/11407695/oleg-valter
  [10]: https://github.com/userscripters
  [11]: https://github.com/userscripters/stackexchange-api-types/issues
  [12]: https://chat.stackoverflow.com/rooms/214345/userscript-newbies-and-friends
  [13]: https://github.com/userscripters/stackexchange-api-types
  [14]: https://github.com/SamVerschueren/tsd
  [15]: https://github.com/userscripters/stackexchange-api-types/pulls