# SDKs

Official libraries for Node.js and Python. Both have no dependencies and are safe by default:

- 3-second timeouts
- retries that respect `retry-after` and never run a check twice
- checks that let messages through when Spamgone can't be reached

> The packages are being published to npm and PyPI. Until they're there, call the API directly, as in the [Quickstart](/docs/quickstart).

## Node.js

```bash
npm install spamgone
```

It needs Node.js 18 or later, and comes with TypeScript types.

```typescript
import { Spamgone } from "spamgone";

const spamgone = new Spamgone({ apiKey: process.env.SPAMGONE_API_KEY });

const check = await spamgone.checks.create({
  text: "Turn $250 into $5,000 in 7 days. DM me on Telegram",
  context: { content_type: "message", author: { id: "user_8412" } },
});

if (check.spam.action === "block") {
  // Hide the message.
}
```

## Python

```bash
pip install spamgone
```

It needs Python 3.9 or later.

```python
from spamgone import Spamgone

spamgone = Spamgone()  # reads SPAMGONE_API_KEY

check = spamgone.checks.create(
    "Turn $250 into $5,000 in 7 days. DM me on Telegram",
    context={"content_type": "message", "author": {"id": "user_8412"}},
)

if check["spam"]["action"] == "block":
    ...  # Hide the message.
```

## What they do for you

| Behavior                                         | Node.js                                            | Python                                              |
| ------------------------------------------------ | -------------------------------------------------- | --------------------------------------------------- |
| Timeout per attempt                              | `timeoutMs`, 3000                                  | `timeout`, 3.0 seconds                              |
| Retries on `429`, `5xx` and network errors       | `maxRetries`, 2                                    | `max_retries`, 2                                    |
| Idempotency key on every POST, reused on retries | `{ idempotencyKey }` to set your own               | `idempotency_key=` to set your own                  |
| When Spamgone can't be reached                   | `failMode: "open"` (default) or `"closed"`         | `fail_mode="open"` (default) or `"closed"`          |
| Hook for degraded checks                         | `onDegraded(error)`                                | `on_degraded(error)`                                |
| Errors                                           | `SpamgoneError` with `name`, `status`, `requestId` | `SpamgoneError` with `name`, `status`, `request_id` |

Retries wait at least as long as `retry-after` says. A wait over 10 seconds, such as a quota that resets tomorrow, fails at once instead of holding your request open.

## Failing open

`checks.create` and `checks.batch` fail open by default. When Spamgone can't be reached, times out, or keeps answering with a server error after the retries, they return:

- `allow` as the action
- `degraded: true`
- no check ID

They also call your `onDegraded` (Node) or `on_degraded` (Python) hook. An outage never stops your users this way. Client errors, such as a wrong key, an invalid request or a used-up quota, still raise, because they need a fix on your side.

Set the fail mode to `closed` to raise instead. Every other method always raises.

## Verify webhooks

Both libraries check the `spamgone-signature` header against the raw body, in constant time. They refuse deliveries signed more than 5 minutes ago.

```typescript
import { verifyWebhook } from "spamgone";

const event = verifyWebhook({
  payload: await request.text(),
  signature: request.headers.get("spamgone-signature"),
  secret: process.env.SPAMGONE_WEBHOOK_SECRET,
});
```

```python
from spamgone import verify_webhook

event = verify_webhook(
    request.body,
    request.headers.get("spamgone-signature"),
    os.environ["SPAMGONE_WEBHOOK_SECRET"],
)
```

Pass the body exactly as it arrived, before any JSON parsing. See [Webhooks](/docs/webhooks) for the events.

## Every endpoint

Both libraries cover the whole API with the same resources: `checks`, API keys, `rules`, `settings`, `usage` and `webhooks`. Node uses camelCase (`spamgone.apiKeys.rotate`) and Python snake_case (`spamgone.api_keys.rotate`). The [Checks reference](/docs/checks) and [API keys](/docs/api-keys) pages describe each call.
