Connector Spec v1

Built-in connectors

10 connectors ship with Astero (one directory each under packages/connectors/) and are configurable from /dashboard/[guildId]/integrations :

Top.gg and Astero-MCP are separate endpoints (not connectors) — /api/topgg/webhook for vote rewards, and /api/mcp-server for LLM tool calls (see MCP Server).

Twitch quick reference

Four trigger types via Twitch EventSub : stream.online, channel.subscribe, channel.follow, channel.raid (all subscribed on install per packages/connectors/twitch/manifest.json). The Streamer Starter Kit preset creates 3 IntegrationMappings in one click ( POST /api/bots/:botId/integrations/:installId/preset/twitch-creator).

v1 limitation : actions are announce-only (Discord message). Auto-assign Sub role + XP bonus require Twitch↔Discord account linking, deferred to v2.

Manifest schema

Each connector ships a manifest.json (a static JSON file, not JS). Real shape (excerpt from packages/connectors/twitch/manifest.json) :

{
  "id": "twitch",
  "version": "1.0.0",
  "name": "Twitch",
  "publisher": "astero-official",
  "category": "creator",
  "iconUrl": "https://example.com/your-connector-icon.svg",
  "minPlan": "FREE",
  "description": "Stream notifications, sub/follow events, raid + cheer triggers from Twitch.",
  "oauth": {
    "clientIdEnv": "TWITCH_CLIENT_ID",
    "clientSecretEnv": "TWITCH_CLIENT_SECRET",
    "scopes": ["user:read:subscriptions", "channel:read:subscriptions", "moderator:read:followers"],
    "authorizeUrl": "https://id.twitch.tv/oauth2/authorize",
    "tokenUrl": "https://id.twitch.tv/oauth2/token",
    "tokenRefreshSupported": true
  },
  "webhooks": {
    "verificationStrategy": "twitch-eventsub",
    "secretEnv": "TWITCH_WEBHOOK_SECRET",
    "subscribeOnInstall": ["stream.online", "channel.subscribe", "channel.follow", "channel.raid"]
  },
  "triggers": [
    { "id": "stream.online", "label": "Streamer goes live", "schema": { /* payload shape */ } },
    { "id": "channel.subscribe", "label": "New subscriber", "schema": { /* … */ } },
    { "id": "channel.follow", "label": "New follower", "schema": { /* … */ } },
    { "id": "channel.raid", "label": "Incoming raid", "schema": { /* … */ } }
  ]
}

Built-in webhooks.verificationStrategy values (defined in packages/connectors/_shared/webhookValidator.js) : hmac-sha256, twitch-eventsub, github-webhook.

Available actions

When a trigger fires, mapped actions execute in order. 9 action types are supported by connectorActionExecutor.js :

• discord.sendMessage — channel + content / embed
• discord.replyEmbed — reply to triggering event with embed
• discord.assignRole — give a role to a user
• discord.removeRole — remove a role from a user
• discord.addReaction — add an emoji reaction
• discord.sendDM — DM the user
• discord.giveXpBonus — grant XP (Leveling module)
• astero.giftCodeGrant — auto-redeem a gift code
• astero.logRoiEvent — emit ROI dashboard event

Conditional gating (JSONLogic)

Each mapping can carry a conditionExpr in JSONLogic. The runtime evaluates it against the event payload + workflow context before firing actions.

// Twitch — only fire on Tier-2 subscribers
{"==": [{"var": "tier"}, "2000"]}

// Twitch — only large raids worth alerting staff for
{">=": [{"var": "viewers"}, 10]}

// Patreon — patrons at $10+ tier
{">=": [{"var": "amount_cents"}, 1000]}

Submit a custom connector (ENTERPRISE)

Studio Edition customers can submit custom connectors via POST /api/connector-submissions. Submission includes : manifest JSON, normalizer JS, webhook validator strategy, optional install OAuth metadata. Reviewed by Astero staff before promotion to the marketplace.