@sentinel-unturned/integration-sdk

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

Installation

npm install @sentinel-unturned/integration-sdk zod

Quick Start

1. Create Your Manifest

{
  "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

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

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

3. Handle Webhooks

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

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:

{
  "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