@driftwatch/autopilot 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victory Lucky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @driftwatch/autopilot
+
+Slack, Telegram, and generic-webhook notifiers, plus inbound-webhook signature
+verification, for [DriftWatch](https://github.com/codewithveek/drift-watch)
+Autopilot. A companion to `@driftwatch/sdk` — bring this in only if you use
+those channels; the SDK's approval/scheduler orchestration works against any
+`Notifier` implementation, including your own.
+
+## Install
+
+```bash
+npm install @driftwatch/sdk @driftwatch/autopilot
+```
+
+## Notifiers
+
+Each implements the SDK's `Notifier` interface (`notify(message)`), so they
+plug straight into `NotifierRegistry` / `ApprovalService` / `AutopilotScheduler`
+from `@driftwatch/sdk`:
+
+```ts
+import { SlackNotifier, TelegramNotifier, WebhookNotifier } from '@driftwatch/autopilot';
+import type { NotifierRegistry } from '@driftwatch/sdk';
+
+const notifiers: NotifierRegistry = {
+  slack: new SlackNotifier(process.env.SLACK_WEBHOOK_URL!),
+  telegram: new TelegramNotifier(process.env.TELEGRAM_BOT_TOKEN!, process.env.TELEGRAM_CHAT_ID!),
+  webhook: new WebhookNotifier(process.env.DRIFT_WEBHOOK_URL!),
+  list: [], // populate with whichever of the above you configured
+};
+```
+
+## Verifying inbound callbacks
+
+Approve/Reject buttons post back to your server. These helpers are
+framework-agnostic, it reads the raw body/headers in your HTTP layer and hand them
+over:
+
+```ts
+import { verifySlackSignature, parseSlackInteraction } from '@driftwatch/autopilot';
+
+// Fastify example
+fastify.post('/integrations/slack/actions', async (request, reply) => {
+  const rawBody = request.body as string; // parsed as a raw string, not JSON
+  const ok = verifySlackSignature(
+    rawBody,
+    request.headers['x-slack-request-timestamp'] as string,
+    request.headers['x-slack-signature'] as string,
+    process.env.SLACK_SIGNING_SECRET!,
+  );
+  if (!ok) return reply.code(401).send();
+
+  const interaction = parseSlackInteraction(rawBody);
+  // interaction.approvalId, interaction.decision, interaction.actor
+});
+```
+
+```ts
+import { verifyTelegramSecretToken, parseTelegramCallback, answerTelegramCallback } from '@driftwatch/autopilot';
+
+fastify.post('/integrations/telegram/webhook', async (request, reply) => {
+  const ok = verifyTelegramSecretToken(
+    request.headers['x-telegram-bot-api-secret-token'] as string,
+    process.env.TELEGRAM_SECRET_TOKEN!,
+  );
+  if (!ok) return reply.code(401).send();
+
+  const callback = parseTelegramCallback(request.body);
+  if (!callback) return reply.send({ ok: true }); // not a button tap
+  // callback.approvalId, callback.decision, callback.actor
+});
+```
+
+Full docs: **[drift-watch-docs.vercel.app](https://drift-watch-docs.vercel.app)**.
+
+## License
+
+MIT — see [LICENSE](https://github.com/codewithveek/drift-watch/blob/main/LICENSE).

package/dist/http.d.ts

@@ -0,0 +1,3 @@
+/** Tiny POST-JSON helper with a hard timeout, shared by the notifiers. */
+export declare function postJson(url: string, body: unknown, timeoutMs?: number): Promise<void>;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.js

@@ -0,0 +1,20 @@
+/** Tiny POST-JSON helper with a hard timeout, shared by the notifiers. */
+export async function postJson(url, body, timeoutMs = 5_000) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status} from ${new URL(url).host}`);
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { postJson } from './http.js';
+export { SlackNotifier, SLACK_APPROVE_ACTION_ID, SLACK_REJECT_ACTION_ID, } from './notifiers/slack.js';
+export { TelegramNotifier, TELEGRAM_APPROVE_PREFIX, TELEGRAM_REJECT_PREFIX, } from './notifiers/telegram.js';
+export { WebhookNotifier } from './notifiers/webhook.js';
+export { verifySlackSignature, parseSlackInteraction, type ParsedSlackInteraction, } from './verify/slack.js';
+export { verifyTelegramSecretToken, parseTelegramCallback, answerTelegramCallback, type ParsedTelegramCallback, } from './verify/telegram.js';
+export { constantTimeEqualStrings } from './verify/util.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,8 @@
+export { postJson } from './http.js';
+export { SlackNotifier, SLACK_APPROVE_ACTION_ID, SLACK_REJECT_ACTION_ID, } from './notifiers/slack.js';
+export { TelegramNotifier, TELEGRAM_APPROVE_PREFIX, TELEGRAM_REJECT_PREFIX, } from './notifiers/telegram.js';
+export { WebhookNotifier } from './notifiers/webhook.js';
+export { verifySlackSignature, parseSlackInteraction, } from './verify/slack.js';
+export { verifyTelegramSecretToken, parseTelegramCallback, answerTelegramCallback, } from './verify/telegram.js';
+export { constantTimeEqualStrings } from './verify/util.js';
+//# sourceMappingURL=index.js.map

package/dist/notifiers/slack.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Slack notifier. Posts a Block Kit message to an incoming webhook. When the
+ * message carries an approvalId, it renders Approve/Reject buttons whose
+ * clicks Slack delivers to your `/integrations/slack/actions`-style route —
+ * verify them with `verifySlackSignature` and parse them with
+ * `parseSlackInteraction` from `../verify/slack.js`.
+ */
+import type { NotificationMessage, Notifier } from '@driftwatch/sdk';
+export declare const SLACK_APPROVE_ACTION_ID = "dw_approve";
+export declare const SLACK_REJECT_ACTION_ID = "dw_reject";
+export declare class SlackNotifier implements Notifier {
+    private readonly webhookUrl;
+    readonly channel = "slack";
+    constructor(webhookUrl: string);
+    notify(message: NotificationMessage): Promise<void>;
+    private render;
+}
+//# sourceMappingURL=slack.d.ts.map

package/dist/notifiers/slack.js

@@ -0,0 +1,55 @@
+import { postJson } from '../http.js';
+export const SLACK_APPROVE_ACTION_ID = 'dw_approve';
+export const SLACK_REJECT_ACTION_ID = 'dw_reject';
+export class SlackNotifier {
+    webhookUrl;
+    channel = 'slack';
+    constructor(webhookUrl) {
+        this.webhookUrl = webhookUrl;
+    }
+    async notify(message) {
+        await postJson(this.webhookUrl, this.render(message));
+    }
+    render(message) {
+        const reasons = message.reasons.length
+            ? message.reasons.map((r) => `• ${r}`).join('\n')
+            : '_no specific reasons reported_';
+        const blocks = [
+            {
+                type: 'header',
+                text: { type: 'plain_text', text: `🚨 ${message.title}` },
+            },
+            {
+                type: 'section',
+                text: {
+                    type: 'mrkdwn',
+                    text: `*Severity:* ${message.severity}\n*Reasons:*\n${reasons}\n*Recommended:* ${message.recommendedAction}`,
+                },
+            },
+        ];
+        if (message.approvalId) {
+            blocks.push({
+                type: 'actions',
+                block_id: `dw_approval:${message.approvalId}`,
+                elements: [
+                    {
+                        type: 'button',
+                        style: 'primary',
+                        text: { type: 'plain_text', text: '✅ Approve' },
+                        action_id: SLACK_APPROVE_ACTION_ID,
+                        value: message.approvalId,
+                    },
+                    {
+                        type: 'button',
+                        style: 'danger',
+                        text: { type: 'plain_text', text: '❌ Reject' },
+                        action_id: SLACK_REJECT_ACTION_ID,
+                        value: message.approvalId,
+                    },
+                ],
+            });
+        }
+        return { text: message.title, blocks };
+    }
+}
+//# sourceMappingURL=slack.js.map

package/dist/notifiers/telegram.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Telegram notifier. Sends a message via the Bot API, with an inline keyboard
+ * carrying Approve/Reject buttons when an approvalId is present. Button taps
+ * arrive as `callback_query` updates at your webhook route — parse them with
+ * `parseTelegramCallback` from `../verify/telegram.js`.
+ */
+import type { NotificationMessage, Notifier } from '@driftwatch/sdk';
+export declare const TELEGRAM_APPROVE_PREFIX = "dw_approve:";
+export declare const TELEGRAM_REJECT_PREFIX = "dw_reject:";
+export declare class TelegramNotifier implements Notifier {
+    private readonly botToken;
+    private readonly chatId;
+    readonly channel = "telegram";
+    constructor(botToken: string, chatId: string);
+    notify(message: NotificationMessage): Promise<void>;
+    private render;
+}
+//# sourceMappingURL=telegram.d.ts.map

package/dist/notifiers/telegram.js

@@ -0,0 +1,48 @@
+import { postJson } from '../http.js';
+export const TELEGRAM_APPROVE_PREFIX = 'dw_approve:';
+export const TELEGRAM_REJECT_PREFIX = 'dw_reject:';
+export class TelegramNotifier {
+    botToken;
+    chatId;
+    channel = 'telegram';
+    constructor(botToken, chatId) {
+        this.botToken = botToken;
+        this.chatId = chatId;
+    }
+    async notify(message) {
+        const url = `https://api.telegram.org/bot${this.botToken}/sendMessage`;
+        await postJson(url, this.render(message));
+    }
+    render(message) {
+        const reasons = message.reasons.length
+            ? message.reasons.map((r) => `• ${r}`).join('\n')
+            : '_no specific reasons reported_';
+        const text = `🚨 *${message.title}*\n` +
+            `*Severity:* ${message.severity}\n` +
+            `*Reasons:*\n${reasons}\n` +
+            `*Recommended:* ${message.recommendedAction}`;
+        const payload = {
+            chat_id: this.chatId,
+            text,
+            parse_mode: 'Markdown',
+        };
+        if (message.approvalId) {
+            payload.reply_markup = {
+                inline_keyboard: [
+                    [
+                        {
+                            text: '✅ Approve',
+                            callback_data: `${TELEGRAM_APPROVE_PREFIX}${message.approvalId}`,
+                        },
+                        {
+                            text: '❌ Reject',
+                            callback_data: `${TELEGRAM_REJECT_PREFIX}${message.approvalId}`,
+                        },
+                    ],
+                ],
+            };
+        }
+        return payload;
+    }
+}
+//# sourceMappingURL=telegram.js.map

package/dist/notifiers/webhook.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generic webhook notifier — posts the raw notification payload as JSON to a
+ * caller-supplied URL. This is the extensibility hook: point it at your own
+ * incident tooling, a serverless function, PagerDuty's events API, etc.
+ */
+import type { NotificationMessage, Notifier } from '@driftwatch/sdk';
+export declare class WebhookNotifier implements Notifier {
+    private readonly webhookUrl;
+    readonly channel = "webhook";
+    constructor(webhookUrl: string);
+    notify(message: NotificationMessage): Promise<void>;
+}
+//# sourceMappingURL=webhook.d.ts.map

package/dist/notifiers/webhook.js

@@ -0,0 +1,15 @@
+import { postJson } from '../http.js';
+export class WebhookNotifier {
+    webhookUrl;
+    channel = 'webhook';
+    constructor(webhookUrl) {
+        this.webhookUrl = webhookUrl;
+    }
+    async notify(message) {
+        await postJson(this.webhookUrl, {
+            source: 'driftwatch-autopilot',
+            ...message,
+        });
+    }
+}
+//# sourceMappingURL=webhook.js.map

package/dist/verify/slack.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Verify Slack's v0 signature: HMAC-SHA256 of `v0:{ts}:{body}` with the signing
+ * secret, compared in constant time. Also rejects stale timestamps to defeat
+ * replay attacks. `rawBody` MUST be the exact bytes Slack sent — any
+ * re-serialization changes what the HMAC covers.
+ */
+export declare function verifySlackSignature(rawBody: string, timestamp: string, signature: string, signingSecret: string): boolean;
+export interface ParsedSlackInteraction {
+    approvalId: string;
+    decision: 'approved' | 'rejected';
+    actor: string;
+}
+/** Parse a verified Slack interactive-message form body into a decision. */
+export declare function parseSlackInteraction(rawBody: string): ParsedSlackInteraction | undefined;
+//# sourceMappingURL=slack.d.ts.map

package/dist/verify/slack.js

@@ -0,0 +1,52 @@
+/**
+ * Verification + parsing for Slack's Interactivity callbacks. Framework-
+ * agnostic — your HTTP layer is responsible for reading the raw request body
+ * and headers and handing them to these functions; see docs for a Fastify
+ * example.
+ */
+import { createHmac } from 'node:crypto';
+import { SLACK_APPROVE_ACTION_ID } from '../notifiers/slack.js';
+import { constantTimeEqualStrings } from './util.js';
+const SLACK_TIMESTAMP_TOLERANCE_SEC = 300;
+/**
+ * Verify Slack's v0 signature: HMAC-SHA256 of `v0:{ts}:{body}` with the signing
+ * secret, compared in constant time. Also rejects stale timestamps to defeat
+ * replay attacks. `rawBody` MUST be the exact bytes Slack sent — any
+ * re-serialization changes what the HMAC covers.
+ */
+export function verifySlackSignature(rawBody, timestamp, signature, signingSecret) {
+    if (!timestamp || !signature)
+        return false;
+    const timestampSec = Number(timestamp);
+    if (!Number.isFinite(timestampSec))
+        return false;
+    const skewSec = Math.abs(Date.now() / 1000 - timestampSec);
+    if (skewSec > SLACK_TIMESTAMP_TOLERANCE_SEC)
+        return false;
+    const expected = 'v0=' +
+        createHmac('sha256', signingSecret)
+            .update(`v0:${timestamp}:${rawBody}`)
+            .digest('hex');
+    return constantTimeEqualStrings(signature, expected);
+}
+/** Parse a verified Slack interactive-message form body into a decision. */
+export function parseSlackInteraction(rawBody) {
+    try {
+        const payloadJson = new URLSearchParams(rawBody).get('payload');
+        if (!payloadJson)
+            return undefined;
+        const payload = JSON.parse(payloadJson);
+        const action = payload.actions?.[0];
+        if (!action?.action_id || !action.value)
+            return undefined;
+        return {
+            approvalId: action.value,
+            decision: action.action_id === SLACK_APPROVE_ACTION_ID ? 'approved' : 'rejected',
+            actor: payload.user?.username || payload.user?.id || 'slack-user',
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=slack.js.map

package/dist/verify/telegram.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Compare the `X-Telegram-Bot-Api-Secret-Token` header against the secret you
+ * registered with `setWebhook`, in constant time.
+ */
+export declare function verifyTelegramSecretToken(providedToken: string, expectedToken: string): boolean;
+export interface ParsedTelegramCallback {
+    approvalId: string;
+    decision: 'approved' | 'rejected';
+    actor: string;
+    callbackQueryId: string;
+}
+/**
+ * Parse a Telegram update body into an approval decision. Returns undefined
+ * for updates that aren't an Approve/Reject callback_query (e.g. a plain
+ * message) — the caller should treat that as a no-op, not an error.
+ */
+export declare function parseTelegramCallback(body: unknown): ParsedTelegramCallback | undefined;
+/** Acknowledge a callback_query so Telegram stops showing a loading spinner. */
+export declare function answerTelegramCallback(botToken: string, callbackQueryId: string, text: string): Promise<void>;
+//# sourceMappingURL=telegram.d.ts.map

package/dist/verify/telegram.js

@@ -0,0 +1,55 @@
+/**
+ * Verification + parsing for Telegram's callback_query webhook updates.
+ * Framework-agnostic — your HTTP layer reads the request body/headers and
+ * hands them to these functions; see docs for a Fastify example.
+ */
+import { TELEGRAM_APPROVE_PREFIX, TELEGRAM_REJECT_PREFIX } from '../notifiers/telegram.js';
+import { constantTimeEqualStrings } from './util.js';
+/**
+ * Compare the `X-Telegram-Bot-Api-Secret-Token` header against the secret you
+ * registered with `setWebhook`, in constant time.
+ */
+export function verifyTelegramSecretToken(providedToken, expectedToken) {
+    return constantTimeEqualStrings(providedToken, expectedToken);
+}
+/**
+ * Parse a Telegram update body into an approval decision. Returns undefined
+ * for updates that aren't an Approve/Reject callback_query (e.g. a plain
+ * message) — the caller should treat that as a no-op, not an error.
+ */
+export function parseTelegramCallback(body) {
+    const update = body;
+    const callbackQuery = update?.callback_query;
+    if (!callbackQuery?.id || !callbackQuery.data)
+        return undefined;
+    const data = callbackQuery.data;
+    let decision;
+    let approvalId;
+    if (data.startsWith(TELEGRAM_APPROVE_PREFIX)) {
+        decision = 'approved';
+        approvalId = data.slice(TELEGRAM_APPROVE_PREFIX.length);
+    }
+    else if (data.startsWith(TELEGRAM_REJECT_PREFIX)) {
+        decision = 'rejected';
+        approvalId = data.slice(TELEGRAM_REJECT_PREFIX.length);
+    }
+    else {
+        return undefined;
+    }
+    return {
+        approvalId,
+        decision,
+        actor: callbackQuery.from?.username ||
+            (callbackQuery.from?.id ? String(callbackQuery.from.id) : 'telegram-user'),
+        callbackQueryId: callbackQuery.id,
+    };
+}
+/** Acknowledge a callback_query so Telegram stops showing a loading spinner. */
+export async function answerTelegramCallback(botToken, callbackQueryId, text) {
+    await fetch(`https://api.telegram.org/bot${botToken}/answerCallbackQuery`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ callback_query_id: callbackQueryId, text }),
+    });
+}
+//# sourceMappingURL=telegram.js.map

package/dist/verify/util.d.ts

@@ -0,0 +1,3 @@
+/** Length-safe constant-time string comparison. */
+export declare function constantTimeEqualStrings(a: string, b: string): boolean;
+//# sourceMappingURL=util.d.ts.map

package/dist/verify/util.js

@@ -0,0 +1,10 @@
+import { timingSafeEqual } from 'node:crypto';
+/** Length-safe constant-time string comparison. */
+export function constantTimeEqualStrings(a, b) {
+    const bufferA = Buffer.from(a);
+    const bufferB = Buffer.from(b);
+    if (bufferA.length !== bufferB.length)
+        return false;
+    return timingSafeEqual(bufferA, bufferB);
+}
+//# sourceMappingURL=util.js.map

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@driftwatch/autopilot",
+  "version": "0.2.1",
+  "description": "Slack, Telegram, and generic-webhook notifiers plus inbound-webhook signature verification for DriftWatch Autopilot. Companion to @driftwatch/sdk — bring these in only if you use those channels.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Victory Lucky",
+  "homepage": "https://github.com/codewithveek/drift-watch#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codewithveek/drift-watch.git",
+    "directory": "packages/autopilot"
+  },
+  "bugs": {
+    "url": "https://github.com/codewithveek/drift-watch/issues"
+  },
+  "keywords": [
+    "ai-agent",
+    "autopilot",
+    "slack",
+    "telegram",
+    "webhook",
+    "drift-detection"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@driftwatch/sdk": "0.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}