npm package: @sentinel-unturned/integration-sdk
Description: SDK for building Sentinel integrations with full TypeScript support
Author: Sentinel Team
Latest version: 1.0.0

# @sentinel-unturned/integration-sdk

Build type-safe integrations for Sentinel with full TypeScript support.

## Installation

```bash
npm install @sentinel-unturned/integration-sdk zod
```

## Quick Start

### 1. Create Your Manifest

```json
{
  "name": "my-integration",
  "slug": "my-integration",
  "displayName": "My Integration",
  "description": "Does something cool",
  "version": "1.0.0",
  "author": "Your Name",
  "license": "MIT",
  "scope": "organization",
  "events": {
    "subscribes": ["player.created", "moderation.ban.*"]
  },
  "config": {
    "webhookUrl": {
      "type": "string",
      "required": true,
      "description": "Where to send events"
    }
  }
}
```

### 2. Validate Your Manifest

```typescript
import { validateManifest } from '@sentinel-unturned/integration-sdk';

const result = validateManifest(manifest);
if (!result.success) {
  console.error('Invalid manifest:', result.errors);
}
```

### 3. Handle Webhooks

```typescript
import {
  createWebhookRouter,
  successResponse,
  EVENTS,
} from '@sentinel-unturned/integration-sdk';

const router = createWebhookRouter({
  [EVENTS.PLAYER.CREATED]: async (payload) => {
    console.log('New player:', payload.data.name);
    return successResponse('Processed');
  },

  [EVENTS.MODERATION.BAN_CREATED]: async (payload) => {
    const { player, reason, duration } = payload.data;
    console.log(`${player.name} banned for: ${reason}`);
    return successResponse();
  },
});

// Express example
app.post('/webhook', async (req, res) => {
  const result = await router(req.body);
  res.json(result);
});
```

### 4. Verify Webhook Signatures

```typescript
import { verifyWebhookSignature } from '@sentinel-unturned/integration-sdk';

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-sentinel-signature'];
  const isValid = verifyWebhookSignature(
    req.body.toString(),
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook...
});
```

## API Reference

### Types

- `IntegrationManifest` - Complete manifest structure
- `WebhookPayload<T>` - Typed webhook payload
- `EventType` - All event type strings
- `EventPayload<T>` - Payload for specific event type

### Validators

- `validateManifest(manifest)` - Validate manifest object
- `parseManifest(manifest)` - Parse and validate (throws on error)
- `manifestSchema` - Zod schema for manifest

### Helpers

- `createWebhookRouter(handlers)` - Create typed event router
- `verifyWebhookSignature(payload, signature, secret)` - Verify HMAC signature
- `successResponse(message?, data?)` - Create success response
- `errorResponse(message)` - Create error response

### Constants

- `EVENTS` - All event name constants
- `EVENT_PATTERNS` - Wildcard patterns for subscriptions

## Event Types

### Player Events
- `player.created` - New player registered
- `player.updated` - Player data updated
- `player.connected` - Player joined server
- `player.disconnected` - Player left server

### Moderation Events
- `moderation.ban.created` - Player banned
- `moderation.ban.removed` - Ban lifted
- `moderation.kick.created` - Player kicked
- `moderation.warn.created` - Player warned
- `moderation.mute.created` - Player muted
- `moderation.mute.removed` - Mute lifted

### Server Events
- `gameserver.connected` - Server came online
- `gameserver.disconnected` - Server went offline

### Organization Events
- `organization.created` - Organization created
- `organization.updated` - Organization updated
- `organization.deleted` - Organization deleted
- `organization.member.added` - Member added
- `organization.member.removed` - Member removed

### Integration Events
- `integration.installed` - Integration installed
- `integration.uninstalled` - Integration removed
- `integration.enabled` - Integration enabled
- `integration.disabled` - Integration disabled
- `integration.configured` - Configuration updated

## Wildcard Patterns

Subscribe to multiple events using patterns:

```json
{
  "events": {
    "subscribes": [
      "player.*",
      "moderation.ban.*",
      "*"
    ]
  }
}
```

Available patterns:
- `*` - All events
- `player.*` - All player events
- `moderation.*` - All moderation events
- `moderation.ban.*` - Ban created/removed
- `moderation.mute.*` - Mute created/removed
- `gameserver.*` - Server connect/disconnect
- `organization.*` - All organization events
- `integration.*` - All integration events

## Examples

See the `examples/` directory for complete integration examples:

- `discord-notifier` - Send events to Discord

## License

MIT