> For the complete documentation index, see [llms.txt](https://openblacklist.gitbook.io/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://openblacklist.gitbook.io/api/modules/nodejs.md).

# Node.js Module

## Install the package

First, install it with npm or your favourite package manager

{% tabs %}
{% tab title="Npm" %}

```bash
npm install openblacklist
```

{% endtab %}

{% tab title="Pnpm" %}

```bash
pnpm add openblacklist
```

{% endtab %}

{% tab title="Yarn" %}

```bash
yarn add openblacklist
```

{% endtab %}
{% endtabs %}

And import it in your app like so:

```javascript
import { BlacklistClient } from "openblacklist"
```

## Now, let's use it !

The syntax is very inspired by [discord.js](https://discord.js.org) !

Create a Client with the BlacklistClient class

```javascript
import { BlacklistClient } from "openblacklist"

const client = new BlacklistClient({ // Create your client
    key: "your-obl-key",
    path: "/urlpath",
    pass: "urlpass"
})
```

### Recieve Post Requests

Listen on a port to recieve POST requests

<pre class="language-javascript"><code class="lang-javascript"><strong>client.listen(3000) : Promise&#x3C;void> // 3000, or the port your app runs !
</strong></code></pre>

And listen for event like, ready, add or remove !

```javascript
client.on("ready", (port) => {
    console.log(`OpenBlacklist is now ready on port ${port} !`
})

client.on("add", (bl) => {
    console.log(`Member ${bl.user.username} (${bl.user.id}) was blacklisted !`)
})
```

### Send Get Requests

There is actually only one method for that and it's the client.checkUser function !

Here is how to use it:

<pre class="language-javascript"><code class="lang-javascript"><strong>client.checkUser(id) : Promise&#x3C;Blacklist>
</strong></code></pre>

```javascript
// Check if user is blacklisted
const response = await client.checkUser("840749770221682689")

/*
{
  isBlacklisted: true,
  user: { id: '840749770221682689', username: 'kingqs' },
  reasons: {
    fr: 'Raid, spam, massping',
    en: 'Raid, spam, massping',
    es: 'Incursión, spam, envío masivo'
  }
}
*/

if(!response.isBlacklisted) console.log("User is not blacklisted...")
else console.log(`User ${response.user.username} is blacklisted for the reason:
"${response.reasons.en}" !`)
```

And that's pretty much it !

Yeah it's short but organises your code and makes it simple for you !

## JS API Documentation

### Methods

<table><thead><tr><th width="240">Method</th><th width="292">Description</th><th>Returns</th></tr></thead><tbody><tr><td>on(event, callback)</td><td>Listens for an event</td><td></td></tr><tr><td>off(event)</td><td>Unlistens for an event</td><td></td></tr><tr><td>listen(port)</td><td>Listen api calls to a port</td><td>Promise&#x3C;void></td></tr><tr><td>checkUser(id)</td><td>Checks if an user is blacklisted</td><td>Promise&#x3C;Blacklist></td></tr></tbody></table>

### Events

<table><thead><tr><th width="141">Name</th><th width="411">Description</th><th>Fields</th></tr></thead><tbody><tr><td>ready</td><td>Emits when express is ready</td><td>port : number</td></tr><tr><td>add</td><td>Emits when someone is added to the blacklist</td><td>blacklist : Blacklist</td></tr><tr><td>remove</td><td>Emits when someone is removed from the blacklist</td><td>blacklist : Blacklist</td></tr></tbody></table>

### Types

```typescript
type BlacklistReasons = {
    fr: string;
    en?: string;
    es?: string;
};

type BlacklistUser = {
    id: string;
    username?: string;
    displayname?: string;
};

type Blacklist = {
    isBlacklisted: boolean;
    user: BlacklistUser;
    reasons?: BlacklistReasons;
};
```