@checkstack/integration-jira-backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# @checkstack/integration-jira-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
+  - @checkstack/integration-common@0.0.2
+  - @checkstack/integration-jira-common@0.0.2
+
+## 0.0.3
+
+### Patch Changes
+
+- 4c5aa9e: Fix `IntegrationProvider.testConnection` generic type
+
+  - **Breaking**: `testConnection` now receives `TConnection` (connection config) instead of `TConfig` (subscription config)
+  - **Breaking**: `RegisteredIntegrationProvider` now includes `TConnection` generic parameter
+  - Removed `testConnection` from webhook provider (providers without `connectionSchema` cannot have `testConnection`)
+  - Fixed Jira provider to use `JiraConnectionConfig` directly in `testConnection`
+
+  This aligns the interface with the actual behavior: `testConnection` tests connection credentials, not subscription configuration.
+
+- 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
+  - @checkstack/integration-common@0.1.1
+  - @checkstack/integration-jira-common@0.0.3
+
+## 0.0.2
+
+### Patch Changes
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [4dd644d]
+- Updated dependencies [71275dd]
+- Updated dependencies [ae19ff6]
+- Updated dependencies [b55fae6]
+- Updated dependencies [b354ab3]
+- Updated dependencies [81f3f85]
+  - @checkstack/common@0.1.0
+  - @checkstack/backend-api@1.0.0
+  - @checkstack/integration-common@0.1.0
+  - @checkstack/integration-backend@0.0.2
+  - @checkstack/integration-jira-common@0.0.2

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@checkstack/integration-jira-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/integration-common": "workspace:*",
+    "@checkstack/integration-jira-common": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "@orpc/server": "^1.13.2",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.0.0",
+    "typescript": "^5.0.0",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+import {
+  createBackendPlugin,
+  coreServices,
+} from "@checkstack/backend-api";
+import { integrationProviderExtensionPoint } from "@checkstack/integration-backend";
+import { pluginMetadata } from "@checkstack/integration-jira-common";
+import { createJiraProvider } from "./provider";
+
+export const jiraPlugin = createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    // Register the Jira provider
+    env.registerInit({
+      deps: {
+        logger: coreServices.logger,
+      },
+      init: async ({ logger }) => {
+        logger.debug("🔌 Registering Jira Integration Provider...");
+
+        // Create and register the Jira provider
+        // No dependencies needed - connection access is provided through context/params
+        const jiraProvider = createJiraProvider();
+        const integrationExt = env.getExtensionPoint(
+          integrationProviderExtensionPoint
+        );
+        integrationExt.addProvider(jiraProvider, pluginMetadata);
+
+        logger.info("✅ Jira Integration Plugin registered");
+      },
+    });
+  },
+});
+
+export default jiraPlugin;

package/src/jira-client.ts

@@ -0,0 +1,332 @@
+import type { Logger } from "@checkstack/backend-api";
+import type {
+  JiraProject,
+  JiraIssueType,
+  JiraField,
+  JiraConnection,
+} from "@checkstack/integration-jira-common";
+
+/**
+ * Connection config for generic connection management.
+ * Mirrors the structure from provider.ts.
+ */
+export interface JiraConnectionConfig {
+  baseUrl: string;
+  email: string;
+  apiToken: string;
+}
+
+/**
+ * Response from creating a Jira issue.
+ */
+export interface CreateIssueResult {
+  /** Issue ID */
+  id: string;
+  /** Issue key (e.g., "PROJ-123") */
+  key: string;
+  /** Self URL */
+  self: string;
+}
+
+/**
+ * Priority from Jira API.
+ */
+export interface JiraPriority {
+  id: string;
+  name: string;
+  iconUrl?: string;
+}
+
+/**
+ * Issue creation payload.
+ */
+export interface CreateIssuePayload {
+  projectKey: string;
+  issueTypeId: string;
+  summary: string;
+  description?: string;
+  priorityId?: string;
+  additionalFields?: Record<string, unknown>;
+}
+
+/**
+ * Options for creating a Jira client.
+ */
+interface JiraClientOptions {
+  baseUrl: string;
+  email: string;
+  apiToken: string;
+  logger: Logger;
+}
+
+/**
+ * Create a typed Jira REST API client.
+ */
+export function createJiraClient(options: JiraClientOptions) {
+  const { baseUrl, email, apiToken, logger } = options;
+
+  // Build basic auth header
+  const authHeader = `Basic ${Buffer.from(`${email}:${apiToken}`).toString(
+    "base64"
+  )}`;
+
+  /**
+   * Make an authenticated request to the Jira API.
+   */
+  async function request<T>(path: string, init?: RequestInit): Promise<T> {
+    const url = `${baseUrl.replace(/\/$/, "")}/rest/api/3${path}`;
+
+    const response = await fetch(url, {
+      ...init,
+      headers: {
+        Authorization: authHeader,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...init?.headers,
+      },
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      logger.error(
+        `Jira API error: ${response.status} ${response.statusText}`,
+        { url, error: errorText }
+      );
+      throw new Error(`Jira API error: ${response.status} - ${errorText}`);
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  return {
+    /**
+     * Test connection by fetching the current user.
+     */
+    async testConnection(): Promise<{ success: boolean; message?: string }> {
+      try {
+        await request<{ accountId: string }>("/myself");
+        return { success: true };
+      } catch (error) {
+        return {
+          success: false,
+          message: error instanceof Error ? error.message : "Unknown error",
+        };
+      }
+    },
+
+    /**
+     * Get all accessible projects.
+     */
+    async getProjects(): Promise<JiraProject[]> {
+      interface ProjectResponse {
+        id: string;
+        key: string;
+        name: string;
+        avatarUrls?: Record<string, string>;
+      }
+
+      const result = await request<ProjectResponse[]>("/project");
+      return result.map((p) => ({
+        id: p.id,
+        key: p.key,
+        name: p.name,
+        avatarUrls: p.avatarUrls,
+      }));
+    },
+
+    /**
+     * Get issue types for a project.
+     * Uses the /project/{projectIdOrKey}?expand=issueTypes endpoint.
+     */
+    async getIssueTypes(projectKey: string): Promise<JiraIssueType[]> {
+      interface ProjectWithIssueTypes {
+        id: string;
+        key: string;
+        name: string;
+        issueTypes: Array<{
+          id: string;
+          name: string;
+          description?: string;
+          iconUrl?: string;
+          subtask: boolean;
+        }>;
+      }
+
+      logger.debug(`Fetching issue types for project: ${projectKey}`);
+
+      const result = await request<ProjectWithIssueTypes>(
+        `/project/${encodeURIComponent(projectKey)}?expand=issueTypes`
+      );
+
+      logger.debug(
+        `Found ${
+          result.issueTypes?.length ?? 0
+        } issue types for project ${projectKey}`
+      );
+
+      // Filter out subtasks for simpler UX
+      return (result.issueTypes || [])
+        .filter((t) => !t.subtask)
+        .map((t) => ({
+          id: t.id,
+          name: t.name,
+          description: t.description,
+          iconUrl: t.iconUrl,
+          subtask: t.subtask,
+        }));
+    },
+
+    /**
+     * Get fields available for creating issues with a specific type.
+     * Uses the /issue/createmeta/{projectIdOrKey}/issuetypes/{issueTypeId} endpoint.
+     */
+    async getFields(
+      projectKey: string,
+      issueTypeId: string
+    ): Promise<JiraField[]> {
+      interface FieldsResponse {
+        startAt: number;
+        maxResults: number;
+        total: number;
+        fields: Array<{
+          key: string;
+          fieldId: string;
+          name: string;
+          required: boolean;
+          schema?: {
+            type: string;
+            system?: string;
+            custom?: string;
+            customId?: number;
+          };
+          allowedValues?: Array<{
+            id: string;
+            name?: string;
+            value?: string;
+          }>;
+        }>;
+      }
+
+      logger.debug(
+        `Fetching fields for project: ${projectKey}, issueType: ${issueTypeId}`
+      );
+
+      const result = await request<FieldsResponse>(
+        `/issue/createmeta/${encodeURIComponent(
+          projectKey
+        )}/issuetypes/${encodeURIComponent(issueTypeId)}`
+      );
+
+      logger.debug(
+        `Found ${
+          result.fields?.length ?? 0
+        } fields for project ${projectKey}, issueType ${issueTypeId}`
+      );
+
+      return (result.fields || []).map((field) => ({
+        key: field.key || field.fieldId,
+        name: field.name,
+        required: field.required,
+        schema: field.schema,
+        allowedValues: field.allowedValues,
+      }));
+    },
+
+    /**
+     * Get available priorities.
+     */
+    async getPriorities(): Promise<JiraPriority[]> {
+      interface PriorityResponse {
+        id: string;
+        name: string;
+        iconUrl?: string;
+      }
+
+      const result = await request<PriorityResponse[]>("/priority");
+      return result.map((p) => ({
+        id: p.id,
+        name: p.name,
+        iconUrl: p.iconUrl,
+      }));
+    },
+
+    /**
+     * Create a new issue.
+     */
+    async createIssue(payload: CreateIssuePayload): Promise<CreateIssueResult> {
+      const {
+        projectKey,
+        issueTypeId,
+        summary,
+        description,
+        priorityId,
+        additionalFields,
+      } = payload;
+
+      // Build the issue fields
+      const fields: Record<string, unknown> = {
+        project: { key: projectKey },
+        issuetype: { id: issueTypeId },
+        summary,
+        ...additionalFields,
+      };
+
+      if (description) {
+        // Use Atlassian Document Format for description
+        fields.description = {
+          type: "doc",
+          version: 1,
+          content: [
+            {
+              type: "paragraph",
+              content: [{ type: "text", text: description }],
+            },
+          ],
+        };
+      }
+
+      if (priorityId) {
+        fields.priority = { id: priorityId };
+      }
+
+      return request<CreateIssueResult>("/issue", {
+        method: "POST",
+        body: JSON.stringify({ fields }),
+      });
+    },
+  };
+}
+
+/**
+ * Create a Jira client from a generic connection config.
+ * Used with the generic connection management system.
+ */
+export function createJiraClientFromConfig(
+  config: JiraConnectionConfig,
+  logger: Logger
+) {
+  return createJiraClient({
+    baseUrl: config.baseUrl,
+    email: config.email,
+    apiToken: config.apiToken,
+    logger,
+  });
+}
+
+/**
+ * Create a Jira client from a connection configuration.
+ * @deprecated Use createJiraClientFromConfig with generic connection management.
+ */
+export function createJiraClientFromConnection(
+  connection: JiraConnection,
+  logger: Logger
+) {
+  return createJiraClient({
+    baseUrl: connection.baseUrl,
+    email: connection.email,
+    apiToken: connection.apiToken,
+    logger,
+  });
+}
+
+export type JiraClient = ReturnType<typeof createJiraClient>;

package/src/provider.ts

@@ -0,0 +1,377 @@
+import { z } from "zod";
+import { Versioned, configString } from "@checkstack/backend-api";
+import type {
+  IntegrationProvider,
+  IntegrationDeliveryContext,
+  IntegrationDeliveryResult,
+  TestConnectionResult,
+  ConnectionOption,
+  GetConnectionOptionsParams,
+} from "@checkstack/integration-backend";
+import { createJiraClient, createJiraClientFromConfig } from "./jira-client";
+import { expandTemplate } from "./template-engine";
+
+/**
+ * Schema for Jira connection configuration.
+ * Uses configString with x-secret for API token encryption and automatic redaction.
+ */
+export const JiraConnectionConfigSchema = z.object({
+  baseUrl: configString({}).url().describe("Jira Cloud base URL"),
+  email: configString({}).email().describe("Jira user email"),
+  apiToken: configString({ "x-secret": true }).describe("Jira API token"),
+});
+
+export type JiraConnectionConfig = z.infer<typeof JiraConnectionConfigSchema>;
+
+/**
+ * Resolver names for dynamic dropdowns.
+ * Defined as constants to ensure consistency between schema and handler.
+ */
+export const JIRA_RESOLVERS = {
+  PROJECT_OPTIONS: "projectOptions",
+  ISSUE_TYPE_OPTIONS: "issueTypeOptions",
+  PRIORITY_OPTIONS: "priorityOptions",
+  FIELD_OPTIONS: "fieldOptions",
+} as const;
+
+/**
+ * Dynamic field mapping schema with options resolver for field key.
+ * Uses configString with x-options-resolver to fetch available fields from Jira.
+ */
+export const DynamicJiraFieldMappingSchema = z.object({
+  /** Jira field key - fetched dynamically from Jira */
+  fieldKey: configString({
+    "x-options-resolver": JIRA_RESOLVERS.FIELD_OPTIONS,
+    "x-depends-on": ["projectKey", "issueTypeId"],
+    "x-searchable": true,
+  }).describe("Jira field"),
+  /** Template string with {{payload.property}} placeholders */
+  template: configString({}).describe("Template value"),
+});
+
+/**
+ * Provider configuration for Jira subscriptions.
+ * Uses configString with x-options-resolver for dynamic dropdowns.
+ * Uses configString with x-hidden for connectionId which is auto-populated.
+ */
+export const JiraSubscriptionConfigSchema = z.object({
+  /** ID of the site-wide Jira connection to use (auto-populated) */
+  connectionId: configString({ "x-hidden": true }).describe(
+    "Jira connection to use"
+  ),
+  /** Jira project key to create issues in */
+  projectKey: configString({
+    "x-options-resolver": JIRA_RESOLVERS.PROJECT_OPTIONS,
+  }).describe("Project key"),
+  /** Issue type ID for created issues */
+  issueTypeId: configString({
+    "x-options-resolver": JIRA_RESOLVERS.ISSUE_TYPE_OPTIONS,
+    "x-depends-on": ["projectKey"],
+  }).describe("Issue type"),
+  /** Summary template (required - uses {{payload.field}} syntax) */
+  summaryTemplate: configString({}).min(1).describe("Issue summary template"),
+  /** Description template (optional) */
+  descriptionTemplate: configString({})
+    .optional()
+    .describe("Issue description template"),
+  /** Priority ID (optional) */
+  priorityId: configString({
+    "x-options-resolver": JIRA_RESOLVERS.PRIORITY_OPTIONS,
+  })
+    .describe("Priority")
+    .optional(),
+  /** Additional field mappings */
+  fieldMappings: z
+    .array(DynamicJiraFieldMappingSchema)
+    .optional()
+    .describe("Additional field mappings"),
+});
+
+/**
+ * Jira subscription config type.
+ */
+export type JiraProviderConfig = z.infer<typeof JiraSubscriptionConfigSchema>;
+
+/**
+ * Create the Jira integration provider.
+ * Uses the generic connection management system for site-wide Jira connections.
+ * Connection access is provided through params/context at call time.
+ */
+export function createJiraProvider(): IntegrationProvider<
+  JiraProviderConfig,
+  JiraConnectionConfig
+> {
+  return {
+    id: "jira",
+    displayName: "Jira",
+    description: "Create Jira issues from integration events",
+    icon: "Ticket",
+
+    // Subscription configuration schema
+    config: new Versioned({
+      version: 1,
+      schema: JiraSubscriptionConfigSchema,
+    }),
+
+    // Connection configuration schema for generic connection management
+    connectionSchema: new Versioned({
+      version: 1,
+      schema: JiraConnectionConfigSchema,
+    }),
+
+    documentation: {
+      setupGuide: `
+## Jira Integration Setup
+
+1. **Create a Jira Connection**: First, set up a site-wide Jira connection with your Atlassian credentials.
+2. **Configure the Subscription**: Select your connection, project, and issue type.
+3. **Set Up Templates**: Use \`{{payload.property}}\` syntax to dynamically populate issue fields from event data.
+
+### Template Syntax
+
+Use double curly braces to reference event payload properties:
+- \`{{payload.title}}\` - Direct property access
+- \`{{payload.system.name}}\` - Nested property access
+
+If a property is missing, the placeholder will be preserved in the output for debugging.
+      `.trim(),
+      examplePayload: JSON.stringify(
+        {
+          eventType: "incident.created",
+          timestamp: "2024-01-15T10:30:00Z",
+          payload: {
+            title: "Database Connectivity Issue",
+            description: "Unable to connect to production database",
+            severity: "high",
+            system: {
+              id: "sys-123",
+              name: "Production Database",
+            },
+          },
+        },
+        undefined,
+        2
+      ),
+    },
+
+    /**
+     * Get dynamic options for subscription configuration fields.
+     * Provides cascading dropdowns: connection -> projects -> issueTypes -> priorities
+     */
+    async getConnectionOptions(
+      params: GetConnectionOptionsParams
+    ): Promise<ConnectionOption[]> {
+      const {
+        connectionId,
+        resolverName,
+        context,
+        getConnectionWithCredentials,
+        logger,
+      } = params;
+
+      // Fetch the connection with credentials
+      const connection = await getConnectionWithCredentials(connectionId);
+      if (!connection) {
+        return [];
+      }
+
+      // Type-safe config access
+      const config = connection.config as JiraConnectionConfig;
+
+      const client = createJiraClientFromConfig(config, logger);
+
+      try {
+        switch (resolverName) {
+          case JIRA_RESOLVERS.PROJECT_OPTIONS: {
+            const projects = await client.getProjects();
+            return projects.map((p) => ({
+              value: p.key,
+              label: `${p.name} (${p.key})`,
+            }));
+          }
+
+          case JIRA_RESOLVERS.ISSUE_TYPE_OPTIONS: {
+            const projectKey = context?.projectKey as string | undefined;
+            if (!projectKey) {
+              return [];
+            }
+            const issueTypes = await client.getIssueTypes(projectKey);
+            return issueTypes.map((t) => ({
+              value: t.id,
+              label: t.name,
+            }));
+          }
+
+          case JIRA_RESOLVERS.PRIORITY_OPTIONS: {
+            const priorities = await client.getPriorities();
+            return priorities.map((p) => ({
+              value: p.id,
+              label: p.name,
+            }));
+          }
+
+          case JIRA_RESOLVERS.FIELD_OPTIONS: {
+            const projectKey = context?.projectKey as string | undefined;
+            const issueTypeId = context?.issueTypeId as string | undefined;
+            if (!projectKey || !issueTypeId) {
+              return [];
+            }
+            const fields = await client.getFields(projectKey, issueTypeId);
+            // Filter out standard fields that are handled separately
+            const excludedFields = new Set([
+              "summary",
+              "description",
+              "priority",
+              "issuetype",
+              "project",
+              "reporter",
+              "assignee",
+            ]);
+            return fields
+              .filter((f) => !excludedFields.has(f.key))
+              .map((f) => ({
+                value: f.key,
+                label: `${f.name}${f.required ? " *" : ""}`,
+              }));
+          }
+
+          default: {
+            logger.error(`Unknown resolver name: ${resolverName}`);
+            return [];
+          }
+        }
+      } catch (error) {
+        logger.error("Failed to get connection options", error);
+        return [];
+      }
+    },
+
+    /**
+     * Test the connection configuration.
+     */
+    async testConnection(
+      config: JiraConnectionConfig
+    ): Promise<TestConnectionResult> {
+      const minimalLogger = {
+        debug: () => {},
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+      };
+
+      const client = createJiraClientFromConfig(config, minimalLogger);
+      return client.testConnection();
+    },
+
+    /**
+     * Deliver an event by creating a Jira issue.
+     */
+    async deliver(
+      context: IntegrationDeliveryContext<JiraProviderConfig>
+    ): Promise<IntegrationDeliveryResult> {
+      const { providerConfig, event, logger } = context;
+      const {
+        connectionId,
+        projectKey,
+        issueTypeId,
+        summaryTemplate,
+        descriptionTemplate,
+        priorityId,
+        fieldMappings,
+      } = providerConfig;
+
+      // Get the connection with credentials from the delivery context
+      if (!context.getConnectionWithCredentials) {
+        return {
+          success: false,
+          error: "Connection access not available in delivery context",
+        };
+      }
+      const connection = await context.getConnectionWithCredentials(
+        connectionId
+      );
+      if (!connection) {
+        return {
+          success: false,
+          error: `Jira connection not found: ${connectionId}`,
+        };
+      }
+
+      // Type-safe config access
+      const config = connection.config as JiraConnectionConfig;
+
+      // Create Jira client
+      const client = createJiraClient({
+        baseUrl: config.baseUrl,
+        email: config.email,
+        apiToken: config.apiToken,
+        logger,
+      });
+
+      // Expand templates using the event payload
+      const payload = event.payload as Record<string, unknown>;
+      const summary = expandTemplate(summaryTemplate, payload);
+      const description = descriptionTemplate
+        ? expandTemplate(descriptionTemplate, payload)
+        : undefined;
+
+      // Build additional fields from field mappings
+      const additionalFields: Record<string, unknown> = {};
+      if (fieldMappings) {
+        for (const mapping of fieldMappings) {
+          const value = expandTemplate(mapping.template, payload);
+          additionalFields[mapping.fieldKey] = value;
+        }
+      }
+
+      try {
+        // Create the issue
+        const result = await client.createIssue({
+          projectKey,
+          issueTypeId,
+          summary,
+          description,
+          priorityId,
+          additionalFields:
+            Object.keys(additionalFields).length > 0
+              ? additionalFields
+              : undefined,
+        });
+
+        logger.info(`Created Jira issue: ${result.key}`, {
+          issueId: result.id,
+          issueKey: result.key,
+          project: projectKey,
+        });
+
+        return {
+          success: true,
+          externalId: result.key,
+        };
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "Unknown error";
+        logger.error(`Failed to create Jira issue: ${message}`, { error });
+
+        // Check if it's a rate limit error
+        if (
+          message.includes("429") ||
+          message.toLowerCase().includes("rate limit")
+        ) {
+          return {
+            success: false,
+            error: `Rate limited by Jira: ${message}`,
+            retryAfterMs: 60_000, // Retry after 1 minute
+          };
+        }
+
+        return {
+          success: false,
+          error: `Failed to create Jira issue: ${message}`,
+        };
+      }
+    },
+  };
+}
+
+export type JiraProvider = ReturnType<typeof createJiraProvider>;

package/src/template-engine.ts

@@ -0,0 +1,89 @@
+/**
+ * Simple template engine for expanding {{payload.property}} placeholders.
+ * Supports nested property access (e.g., {{payload.system.name}}).
+ * Missing values are rendered as the original placeholder for easier debugging.
+ */
+
+/**
+ * Get a nested property value from an object using dot notation.
+ * @param obj The object to retrieve from
+ * @param path The dot-separated path (e.g., "system.name")
+ * @returns The value at the path, or undefined if not found
+ */
+function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+  const parts = path.split(".");
+  let current: unknown = obj;
+
+  for (const part of parts) {
+    if (current === null || current === undefined) {
+      return undefined;
+    }
+    if (typeof current !== "object") {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+
+  return current;
+}
+
+/**
+ * Expand a template string using values from the payload.
+ *
+ * @param template The template string (e.g., "Alert: {{payload.title}}")
+ * @param payload The payload object containing replacement values
+ * @returns The expanded string with placeholders replaced
+ *
+ * @example
+ * expandTemplate("Issue: {{payload.title}}", { title: "Server down" })
+ * // Returns: "Issue: Server down"
+ *
+ * @example
+ * expandTemplate("{{payload.missing}}", {})
+ * // Returns: "{{payload.missing}}" (original placeholder for debugging)
+ */
+export function expandTemplate(
+  template: string,
+  payload: Record<string, unknown>
+): string {
+  // Match {{payload.path.to.value}} patterns
+  const pattern = /\{\{payload\.([^}]+)\}\}/g;
+
+  return template.replaceAll(pattern, (match, path: string) => {
+    const value = getNestedValue(payload, path);
+
+    // If value is missing, return original placeholder for debugging
+    if (value === undefined || value === null) {
+      return match;
+    }
+
+    // Convert to string
+    if (typeof value === "object") {
+      return JSON.stringify(value);
+    }
+
+    return String(value);
+  });
+}
+
+/**
+ * Check if a template contains any placeholders.
+ */
+export function hasPlaceholders(template: string): boolean {
+  return /\{\{payload\.[^}]+\}\}/.test(template);
+}
+
+/**
+ * Extract all placeholder paths from a template.
+ */
+export function extractPlaceholders(template: string): string[] {
+  const pattern = /\{\{payload\.([^}]+)\}\}/g;
+  const paths: string[] = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = pattern.exec(template)) !== null) {
+    paths.push(match[1]);
+  }
+
+  return paths;
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ]
+}