@checkstack/integration-teams-backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# @checkstack/integration-teams-backend
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/backend-api@0.0.2
+  - @checkstack/common@0.0.2
+  - @checkstack/integration-backend@0.0.2
+
+## 0.1.0
+
+### Minor Changes
+
+- 4c5aa9e: Add Microsoft Teams integration provider - sends events to Teams channels via Graph API
+
+  - Connection schema for Azure AD App credentials (Tenant ID, Client ID, Client Secret)
+  - Dynamic team/channel selection via Graph API
+  - Adaptive Cards for rich event display
+  - Client credentials flow for app-only authentication
+  - Comprehensive documentation for Azure AD setup and permissions
+
+### Patch Changes
+
+- Updated dependencies [4c5aa9e]
+- Updated dependencies [b4eb432]
+- Updated dependencies [a65e002]
+- Updated dependencies [a65e002]
+  - @checkstack/integration-backend@0.1.0
+  - @checkstack/backend-api@1.1.0
+  - @checkstack/common@0.2.0

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@checkstack/integration-teams-backend",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/integration-backend": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.0.0",
+    "typescript": "^5.0.0",
+    "@checkstack/tsconfig": "workspace:*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+import { createBackendPlugin } from "@checkstack/backend-api";
+import { providerExtensionPoint } from "@checkstack/integration-backend";
+import { pluginMetadata } from "./plugin-metadata";
+import { teamsProvider } from "./provider";
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    // Get the integration provider extension point
+    const extensionPoint = env.getExtensionPoint(providerExtensionPoint);
+
+    // Register the Teams provider with our plugin metadata
+    extensionPoint.addProvider(teamsProvider, pluginMetadata);
+  },
+});
+
+// Re-export for testing
+export {
+  teamsProvider,
+  TeamsConnectionSchema,
+  TeamsSubscriptionSchema,
+  buildAdaptiveCard,
+} from "./provider";

package/src/plugin-metadata.ts

@@ -0,0 +1,5 @@
+import type { PluginMetadata } from "@checkstack/common";
+
+export const pluginMetadata: PluginMetadata = {
+  pluginId: "integration-teams",
+};

package/src/provider.test.ts

@@ -0,0 +1,486 @@
+import { describe, it, expect, beforeEach, mock, spyOn } from "bun:test";
+import {
+  teamsProvider,
+  TeamsConnectionSchema,
+  TeamsSubscriptionSchema,
+  buildAdaptiveCard,
+} from "./index";
+
+/**
+ * Unit tests for the Microsoft Teams Integration Provider.
+ *
+ * Tests cover:
+ * - Config schema validation
+ * - Connection testing
+ * - Team/channel options resolution
+ * - Adaptive Card building
+ * - Event delivery
+ */
+
+// Mock logger
+const mockLogger = {
+  debug: mock(() => {}),
+  info: mock(() => {}),
+  warn: mock(() => {}),
+  error: mock(() => {}),
+};
+
+describe("Microsoft Teams Integration Provider", () => {
+  beforeEach(() => {
+    mockLogger.debug.mockClear();
+    mockLogger.info.mockClear();
+    mockLogger.warn.mockClear();
+    mockLogger.error.mockClear();
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Provider Metadata
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("metadata", () => {
+    it("has correct basic metadata", () => {
+      expect(teamsProvider.id).toBe("teams");
+      expect(teamsProvider.displayName).toBe("Microsoft Teams");
+      expect(teamsProvider.description).toContain("Teams");
+      expect(teamsProvider.icon).toBe("MessageSquareMore");
+    });
+
+    it("has versioned config and connection schemas", () => {
+      expect(teamsProvider.config).toBeDefined();
+      expect(teamsProvider.config.version).toBe(1);
+      expect(teamsProvider.connectionSchema).toBeDefined();
+      expect(teamsProvider.connectionSchema?.version).toBe(1);
+    });
+
+    it("has documentation", () => {
+      expect(teamsProvider.documentation).toBeDefined();
+      expect(teamsProvider.documentation?.setupGuide).toContain("Azure");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Config Schema Validation
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("connection schema", () => {
+    it("requires all credentials", () => {
+      expect(() => {
+        TeamsConnectionSchema.parse({});
+      }).toThrow();
+
+      expect(() => {
+        TeamsConnectionSchema.parse({
+          tenantId: "tenant-1",
+          clientId: "client-1",
+        });
+      }).toThrow();
+    });
+
+    it("accepts valid connection config", () => {
+      const result = TeamsConnectionSchema.parse({
+        tenantId: "12345678-1234-1234-1234-123456789abc",
+        clientId: "87654321-4321-4321-4321-cba987654321",
+        clientSecret: "super-secret",
+      });
+      expect(result.tenantId).toBe("12345678-1234-1234-1234-123456789abc");
+      expect(result.clientId).toBe("87654321-4321-4321-4321-cba987654321");
+      expect(result.clientSecret).toBe("super-secret");
+    });
+  });
+
+  describe("subscription schema", () => {
+    it("requires all fields", () => {
+      expect(() => {
+        TeamsSubscriptionSchema.parse({});
+      }).toThrow();
+
+      expect(() => {
+        TeamsSubscriptionSchema.parse({ connectionId: "conn-1" });
+      }).toThrow();
+
+      expect(() => {
+        TeamsSubscriptionSchema.parse({
+          connectionId: "conn-1",
+          teamId: "team-1",
+        });
+      }).toThrow();
+    });
+
+    it("accepts valid subscription config", () => {
+      const result = TeamsSubscriptionSchema.parse({
+        connectionId: "conn-1",
+        teamId: "team-123",
+        channelId: "channel-456",
+      });
+      expect(result.connectionId).toBe("conn-1");
+      expect(result.teamId).toBe("team-123");
+      expect(result.channelId).toBe("channel-456");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Adaptive Card Building
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("adaptive card builder", () => {
+    it("builds card with event details", () => {
+      const card = buildAdaptiveCard({
+        eventId: "incident.created",
+        payload: { incidentId: "inc-123", severity: "critical" },
+        subscriptionName: "Critical Incidents",
+        timestamp: "2024-01-15T10:30:00Z",
+      }) as Record<string, unknown>;
+
+      expect(card.type).toBe("AdaptiveCard");
+      expect(card.version).toBe("1.4");
+
+      const body = card.body as Array<Record<string, unknown>>;
+      expect(body.length).toBeGreaterThan(0);
+
+      // Check for event info in FactSet
+      const factSet = body.find((b) => b.type === "FactSet") as Record<
+        string,
+        unknown
+      >;
+      expect(factSet).toBeDefined();
+
+      const facts = factSet.facts as Array<{ title: string; value: string }>;
+      expect(facts.some((f) => f.value === "incident.created")).toBe(true);
+      expect(facts.some((f) => f.value === "Critical Incidents")).toBe(true);
+    });
+
+    it("includes JSON payload in code block", () => {
+      const card = buildAdaptiveCard({
+        eventId: "test.event",
+        payload: { key: "value" },
+        subscriptionName: "Test",
+        timestamp: new Date().toISOString(),
+      }) as Record<string, unknown>;
+
+      const body = card.body as Array<Record<string, unknown>>;
+      const codeBlock = body.find((b) => b.fontType === "monospace") as Record<
+        string,
+        unknown
+      >;
+
+      expect(codeBlock).toBeDefined();
+      expect(codeBlock.text).toContain('"key"');
+      expect(codeBlock.text).toContain('"value"');
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Test Connection
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("testConnection", () => {
+    it("returns success when Graph API is accessible", async () => {
+      let requestCount = 0;
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation((async (
+        url: RequestInfo | URL
+      ) => {
+        requestCount++;
+        const urlStr = url.toString();
+
+        // Token request
+        if (urlStr.includes("oauth2/v2.0/token")) {
+          return new Response(
+            JSON.stringify({ access_token: "test-token", expires_in: 3600 }),
+            { status: 200 }
+          );
+        }
+
+        // Teams list request
+        if (urlStr.includes("/teams")) {
+          return new Response(
+            JSON.stringify({
+              value: [
+                { id: "team-1", displayName: "Engineering" },
+                { id: "team-2", displayName: "DevOps" },
+              ],
+            }),
+            { status: 200 }
+          );
+        }
+
+        return new Response("Not Found", { status: 404 });
+      }) as unknown as typeof fetch);
+
+      try {
+        const result = await teamsProvider.testConnection!({
+          tenantId: "tenant-123",
+          clientId: "client-123",
+          clientSecret: "secret-123",
+        });
+
+        expect(result.success).toBe(true);
+        expect(result.message).toContain("2 team(s)");
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("returns failure for auth errors", async () => {
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation(
+        (async () => {
+          return new Response("Unauthorized", { status: 401 });
+        }) as unknown as typeof fetch
+      );
+
+      try {
+        const result = await teamsProvider.testConnection!({
+          tenantId: "tenant-123",
+          clientId: "client-123",
+          clientSecret: "wrong-secret",
+        });
+
+        expect(result.success).toBe(false);
+        expect(result.message).toContain("failed");
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Get Connection Options
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("getConnectionOptions", () => {
+    it("returns team options", async () => {
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation((async (
+        url: RequestInfo | URL
+      ) => {
+        const urlStr = url.toString();
+
+        if (urlStr.includes("oauth2/v2.0/token")) {
+          return new Response(
+            JSON.stringify({ access_token: "test-token", expires_in: 3600 }),
+            { status: 200 }
+          );
+        }
+
+        if (urlStr.includes("/teams") && !urlStr.includes("/channels")) {
+          return new Response(
+            JSON.stringify({
+              value: [
+                { id: "team-1", displayName: "Engineering" },
+                { id: "team-2", displayName: "DevOps" },
+              ],
+            }),
+            { status: 200 }
+          );
+        }
+
+        return new Response("Not Found", { status: 404 });
+      }) as unknown as typeof fetch);
+
+      try {
+        const options = await teamsProvider.getConnectionOptions!({
+          resolverName: "teamOptions",
+          connectionId: "conn-1",
+          context: {},
+          logger: mockLogger,
+          getConnectionWithCredentials: async () => ({
+            config: {
+              tenantId: "t",
+              clientId: "c",
+              clientSecret: "s",
+            },
+          }),
+        });
+
+        expect(options).toHaveLength(2);
+        expect(options[0]).toEqual({ value: "team-1", label: "Engineering" });
+        expect(options[1]).toEqual({ value: "team-2", label: "DevOps" });
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("returns channel options when teamId is provided", async () => {
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation((async (
+        url: RequestInfo | URL
+      ) => {
+        const urlStr = url.toString();
+
+        if (urlStr.includes("oauth2/v2.0/token")) {
+          return new Response(
+            JSON.stringify({ access_token: "test-token", expires_in: 3600 }),
+            { status: 200 }
+          );
+        }
+
+        if (urlStr.includes("/channels")) {
+          return new Response(
+            JSON.stringify({
+              value: [
+                { id: "ch-1", displayName: "General" },
+                { id: "ch-2", displayName: "Alerts" },
+              ],
+            }),
+            { status: 200 }
+          );
+        }
+
+        return new Response("Not Found", { status: 404 });
+      }) as unknown as typeof fetch);
+
+      try {
+        const options = await teamsProvider.getConnectionOptions!({
+          resolverName: "channelOptions",
+          connectionId: "conn-1",
+          context: { teamId: "team-1" },
+          logger: mockLogger,
+          getConnectionWithCredentials: async () => ({
+            config: {
+              tenantId: "t",
+              clientId: "c",
+              clientSecret: "s",
+            },
+          }),
+        });
+
+        expect(options).toHaveLength(2);
+        expect(options[0]).toEqual({ value: "ch-1", label: "General" });
+        expect(options[1]).toEqual({ value: "ch-2", label: "Alerts" });
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("returns empty array when teamId is missing for channel options", async () => {
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation((async (
+        url: RequestInfo | URL
+      ) => {
+        const urlStr = url.toString();
+        if (urlStr.includes("oauth2/v2.0/token")) {
+          return new Response(
+            JSON.stringify({ access_token: "test-token", expires_in: 3600 }),
+            { status: 200 }
+          );
+        }
+        return new Response("Not Found", { status: 404 });
+      }) as unknown as typeof fetch);
+
+      try {
+        const options = await teamsProvider.getConnectionOptions!({
+          resolverName: "channelOptions",
+          connectionId: "conn-1",
+          context: {}, // No teamId
+          logger: mockLogger,
+          getConnectionWithCredentials: async () => ({
+            config: {
+              tenantId: "t",
+              clientId: "c",
+              clientSecret: "s",
+            },
+          }),
+        });
+
+        expect(options).toEqual([]);
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Delivery
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("deliver", () => {
+    it("sends message to Teams channel successfully", async () => {
+      let capturedMessageUrl: string | undefined;
+      let capturedBody: string | undefined;
+
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation((async (
+        url: RequestInfo | URL,
+        options?: RequestInit
+      ) => {
+        const urlStr = url.toString();
+
+        if (urlStr.includes("oauth2/v2.0/token")) {
+          return new Response(
+            JSON.stringify({ access_token: "test-token", expires_in: 3600 }),
+            { status: 200 }
+          );
+        }
+
+        if (urlStr.includes("/messages")) {
+          capturedMessageUrl = urlStr;
+          capturedBody = options?.body as string;
+          return new Response(JSON.stringify({ id: "msg-123" }), {
+            status: 200,
+          });
+        }
+
+        return new Response("Not Found", { status: 404 });
+      }) as unknown as typeof fetch);
+
+      try {
+        const result = await teamsProvider.deliver({
+          event: {
+            eventId: "incident.created",
+            payload: { incidentId: "inc-123" },
+            timestamp: new Date().toISOString(),
+            deliveryId: "del-789",
+          },
+          subscription: {
+            id: "sub-1",
+            name: "Incident Alerts",
+          },
+          providerConfig: {
+            connectionId: "conn-1",
+            teamId: "team-abc",
+            channelId: "channel-xyz",
+          },
+          logger: mockLogger,
+          getConnectionWithCredentials: async () => ({
+            id: "conn-1",
+            config: {
+              tenantId: "t",
+              clientId: "c",
+              clientSecret: "s",
+            },
+          }),
+        });
+
+        expect(result.success).toBe(true);
+        expect(result.externalId).toBe("msg-123");
+        expect(capturedMessageUrl).toContain("team-abc");
+        expect(capturedMessageUrl).toContain("channel-xyz");
+
+        const parsedBody = JSON.parse(capturedBody!);
+        expect(parsedBody.attachments).toHaveLength(1);
+        expect(parsedBody.attachments[0].contentType).toBe(
+          "application/vnd.microsoft.card.adaptive"
+        );
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("returns error when connection not found", async () => {
+      const result = await teamsProvider.deliver({
+        event: {
+          eventId: "test.event",
+          payload: {},
+          timestamp: new Date().toISOString(),
+          deliveryId: "del-1",
+        },
+        subscription: { id: "sub-1", name: "Test" },
+        providerConfig: {
+          connectionId: "nonexistent",
+          teamId: "team-1",
+          channelId: "ch-1",
+        },
+        logger: mockLogger,
+        getConnectionWithCredentials: async () => undefined,
+      });
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("not found");
+    });
+  });
+});

package/src/provider.ts

@@ -0,0 +1,487 @@
+import { z } from "zod";
+import { configString, Versioned } from "@checkstack/backend-api";
+import type {
+  IntegrationProvider,
+  IntegrationDeliveryContext,
+  IntegrationDeliveryResult,
+  GetConnectionOptionsParams,
+  ConnectionOption,
+  TestConnectionResult,
+} from "@checkstack/integration-backend";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Resolver Names
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const TEAMS_RESOLVERS = {
+  TEAM_OPTIONS: "teamOptions",
+  CHANNEL_OPTIONS: "channelOptions",
+} as const;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Configuration Schemas
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Connection configuration - Azure AD App credentials for Graph API.
+ */
+export const TeamsConnectionSchema = z.object({
+  tenantId: configString({}).describe("Azure AD Tenant ID"),
+  clientId: configString({}).describe("Azure AD Application (Client) ID"),
+  clientSecret: configString({ "x-secret": true }).describe(
+    "Azure AD Client Secret"
+  ),
+});
+
+export type TeamsConnectionConfig = z.infer<typeof TeamsConnectionSchema>;
+
+/**
+ * Subscription configuration - which Teams channel to send events to.
+ */
+export const TeamsSubscriptionSchema = z.object({
+  connectionId: configString({ "x-hidden": true }).describe("Teams connection"),
+  teamId: configString({
+    "x-options-resolver": TEAMS_RESOLVERS.TEAM_OPTIONS,
+    "x-depends-on": ["connectionId"],
+  }).describe("Target Team"),
+  channelId: configString({
+    "x-options-resolver": TEAMS_RESOLVERS.CHANNEL_OPTIONS,
+    "x-depends-on": ["connectionId", "teamId"],
+  }).describe("Target Channel"),
+});
+
+export type TeamsSubscriptionConfig = z.infer<typeof TeamsSubscriptionSchema>;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Graph API Types and Client
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const GRAPH_API_BASE = "https://graph.microsoft.com/v1.0";
+
+interface GraphTeam {
+  id: string;
+  displayName: string;
+}
+
+interface GraphChannel {
+  id: string;
+  displayName: string;
+}
+
+interface GraphTeamsResponse {
+  value: GraphTeam[];
+}
+
+interface GraphChannelsResponse {
+  value: GraphChannel[];
+}
+
+interface GraphMessageResponse {
+  id: string;
+}
+
+interface TokenResponse {
+  access_token: string;
+  expires_in: number;
+}
+
+/**
+ * Get an app-only access token using client credentials flow.
+ */
+async function getAppToken(
+  config: TeamsConnectionConfig
+): Promise<
+  { success: true; token: string } | { success: false; error: string }
+> {
+  try {
+    const tokenUrl = `https://login.microsoftonline.com/${config.tenantId}/oauth2/v2.0/token`;
+
+    const response = await fetch(tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: new URLSearchParams({
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+        scope: "https://graph.microsoft.com/.default",
+        grant_type: "client_credentials",
+      }),
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      return {
+        success: false,
+        error: `Token request failed (${response.status}): ${errorText.slice(
+          0,
+          200
+        )}`,
+      };
+    }
+
+    const data = (await response.json()) as TokenResponse;
+    return { success: true, token: data.access_token };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    return { success: false, error: message };
+  }
+}
+
+async function fetchTeams(
+  token: string
+): Promise<
+  { success: true; teams: GraphTeam[] } | { success: false; error: string }
+> {
+  try {
+    const response = await fetch(`${GRAPH_API_BASE}/teams`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+      },
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!response.ok) {
+      return { success: false, error: `Graph API error: ${response.status}` };
+    }
+
+    const data = (await response.json()) as GraphTeamsResponse;
+    return { success: true, teams: data.value ?? [] };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    return { success: false, error: message };
+  }
+}
+
+async function fetchChannels(
+  token: string,
+  teamId: string
+): Promise<
+  | { success: true; channels: GraphChannel[] }
+  | { success: false; error: string }
+> {
+  try {
+    const response = await fetch(`${GRAPH_API_BASE}/teams/${teamId}/channels`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+      },
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!response.ok) {
+      return { success: false, error: `Graph API error: ${response.status}` };
+    }
+
+    const data = (await response.json()) as GraphChannelsResponse;
+    return { success: true, channels: data.value ?? [] };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    return { success: false, error: message };
+  }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Adaptive Card Builder
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+interface AdaptiveCardOptions {
+  eventId: string;
+  payload: Record<string, unknown>;
+  subscriptionName: string;
+  timestamp: string;
+}
+
+export function buildAdaptiveCard(options: AdaptiveCardOptions): object {
+  const { eventId, payload, subscriptionName, timestamp } = options;
+
+  return {
+    type: "AdaptiveCard",
+    $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
+    version: "1.4",
+    body: [
+      {
+        type: "TextBlock",
+        text: `📢 Integration Event`,
+        weight: "bolder",
+        size: "large",
+        wrap: true,
+      },
+      {
+        type: "FactSet",
+        facts: [
+          { title: "Event", value: eventId },
+          { title: "Subscription", value: subscriptionName },
+          { title: "Time", value: new Date(timestamp).toLocaleString() },
+        ],
+      },
+      {
+        type: "TextBlock",
+        text: "**Payload:**",
+        weight: "bolder",
+        spacing: "medium",
+      },
+      {
+        type: "TextBlock",
+        // eslint-disable-next-line unicorn/no-null
+        text: "```\n" + JSON.stringify(payload, null, 2) + "\n```",
+        wrap: true,
+        fontType: "monospace",
+        size: "small",
+      },
+    ],
+  };
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Provider Implementation
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+export const teamsProvider: IntegrationProvider<
+  TeamsSubscriptionConfig,
+  TeamsConnectionConfig
+> = {
+  id: "teams",
+  displayName: "Microsoft Teams",
+  description: "Send integration events to Microsoft Teams channels",
+  icon: "MessageSquareMore",
+
+  config: new Versioned({
+    version: 1,
+    schema: TeamsSubscriptionSchema,
+  }),
+
+  connectionSchema: new Versioned({
+    version: 1,
+    schema: TeamsConnectionSchema,
+  }),
+
+  documentation: {
+    setupGuide: `
+## Register an Azure AD Application
+
+1. Go to [Azure Portal](https://portal.azure.com/) → **Microsoft Entra ID**
+2. Navigate to **App registrations** → **New registration**
+3. Fill in details and register
+
+## Configure API Permissions
+
+1. Go to **API permissions** → **Add a permission** → **Microsoft Graph**
+2. Select **Application permissions** (not Delegated)
+3. Add these permissions:
+   - \`Team.ReadBasic.All\` (to list teams)
+   - \`Channel.ReadBasic.All\` (to list channels)
+   - \`ChannelMessage.Send\` (to send messages)
+4. Click **Grant admin consent**
+
+## Create Client Secret
+
+1. Go to **Certificates & secrets** → **New client secret**
+2. Copy the secret value immediately
+
+## Add App to Teams
+
+For the app to send messages, it must be installed in the target Team:
+1. Create a Teams app manifest or use Graph API to install
+2. Alternatively, ensure the app has \`ChannelMessage.Send\` consent
+    `.trim(),
+  },
+
+  async getConnectionOptions(
+    params: GetConnectionOptionsParams
+  ): Promise<ConnectionOption[]> {
+    const {
+      resolverName,
+      connectionId,
+      context,
+      getConnectionWithCredentials,
+    } = params;
+
+    // Get connection credentials
+    const connection = await getConnectionWithCredentials(connectionId);
+    if (!connection) {
+      return [];
+    }
+
+    const config = connection.config as TeamsConnectionConfig;
+
+    // Get app token
+    const tokenResult = await getAppToken(config);
+    if (!tokenResult.success) {
+      return [];
+    }
+
+    if (resolverName === TEAMS_RESOLVERS.TEAM_OPTIONS) {
+      const result = await fetchTeams(tokenResult.token);
+      if (!result.success) {
+        return [];
+      }
+      return result.teams.map((team) => ({
+        value: team.id,
+        label: team.displayName,
+      }));
+    }
+
+    if (resolverName === TEAMS_RESOLVERS.CHANNEL_OPTIONS) {
+      const teamId = (context as Partial<TeamsSubscriptionConfig>)?.teamId;
+      if (!teamId) {
+        return [];
+      }
+
+      const result = await fetchChannels(tokenResult.token, teamId);
+      if (!result.success) {
+        return [];
+      }
+      return result.channels.map((channel) => ({
+        value: channel.id,
+        label: channel.displayName,
+      }));
+    }
+
+    return [];
+  },
+
+  async testConnection(config: unknown): Promise<TestConnectionResult> {
+    try {
+      const parsedConfig = TeamsConnectionSchema.parse(config);
+      const tokenResult = await getAppToken(parsedConfig);
+
+      if (!tokenResult.success) {
+        return {
+          success: false,
+          message: `Authentication failed: ${tokenResult.error}`,
+        };
+      }
+
+      // Verify we can list teams
+      const teamsResult = await fetchTeams(tokenResult.token);
+      if (!teamsResult.success) {
+        return {
+          success: false,
+          message: `API access failed: ${teamsResult.error}`,
+        };
+      }
+
+      return {
+        success: true,
+        message: `Connected successfully. Found ${teamsResult.teams.length} team(s).`,
+      };
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : "Invalid configuration";
+      return {
+        success: false,
+        message: `Validation failed: ${message}`,
+      };
+    }
+  },
+
+  async deliver(
+    context: IntegrationDeliveryContext<TeamsSubscriptionConfig>
+  ): Promise<IntegrationDeliveryResult> {
+    const { event, subscription, providerConfig, logger } = context;
+
+    // Parse and validate config
+    const config = TeamsSubscriptionSchema.parse(providerConfig);
+
+    // Get connection with credentials
+    if (!context.getConnectionWithCredentials) {
+      return {
+        success: false,
+        error: "Connection credentials not available",
+      };
+    }
+
+    const connection = await context.getConnectionWithCredentials(
+      config.connectionId
+    );
+
+    if (!connection) {
+      return {
+        success: false,
+        error: `Connection not found: ${config.connectionId}`,
+      };
+    }
+
+    const connectionConfig = connection.config as TeamsConnectionConfig;
+
+    // Get app token
+    const tokenResult = await getAppToken(connectionConfig);
+    if (!tokenResult.success) {
+      logger.error("Failed to get Graph API token", {
+        error: tokenResult.error,
+      });
+      return {
+        success: false,
+        error: `Authentication failed: ${tokenResult.error}`,
+      };
+    }
+
+    // Build Adaptive Card
+    const adaptiveCard = buildAdaptiveCard({
+      eventId: event.eventId,
+      payload: event.payload as Record<string, unknown>,
+      subscriptionName: subscription.name,
+      timestamp: event.timestamp,
+    });
+
+    // Send message to channel
+    try {
+      const response = await fetch(
+        `${GRAPH_API_BASE}/teams/${config.teamId}/channels/${config.channelId}/messages`,
+        {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${tokenResult.token}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            body: {
+              contentType: "html",
+              content: `<attachment id="adaptiveCard"></attachment>`,
+            },
+            attachments: [
+              {
+                id: "adaptiveCard",
+                contentType: "application/vnd.microsoft.card.adaptive",
+                content: JSON.stringify(adaptiveCard),
+              },
+            ],
+          }),
+          signal: AbortSignal.timeout(10_000),
+        }
+      );
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        logger.error("Failed to send Teams message", {
+          status: response.status,
+          error: errorText.slice(0, 200),
+        });
+        return {
+          success: false,
+          error: `Graph API error (${response.status}): ${errorText.slice(
+            0,
+            100
+          )}`,
+        };
+      }
+
+      const messageData = (await response.json()) as GraphMessageResponse;
+
+      logger.info("Teams message sent", { messageId: messageData.id });
+      return {
+        success: true,
+        externalId: messageData.id,
+      };
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : "Unknown Graph API error";
+      logger.error("Teams delivery error", { error: message });
+      return {
+        success: false,
+        error: `Failed to send Teams message: ${message}`,
+      };
+    }
+  },
+};

package/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json"
+}