Molecule.dev

@molecule/api-notifications-slack

Provider bond · notifications · API (Node) · v1.0.2 · Apache-2.0

Slack notification provider

npm install @molecule/api-notifications-slack

npm · Source on GitHub · Implements @molecule/api-notifications

How it works

@molecule/api-notifications-slack is a provider bond on the API (Node) side: it implements the notifications core interface (@molecule/api-notifications) with a concrete vendor or library behind it.

Your code calls the core; you wire this provider once at startup. Swapping vendors later is one line in that wiring, not a rewrite.

import { setProvider } from '@molecule/api-notifications'
import { provider } from '@molecule/api-notifications-slack'

setProvider('slack', provider)

Works with: @molecule/api-notifications, @molecule/api-secrets

Secrets: NOTIFICATIONS_SLACK_WEBHOOK_URL

Reference

Slack notifications provider for molecule.dev.

Sends notifications to a Slack channel via an incoming webhook (NOTIFICATIONS_SLACK_WEBHOOK_URL or createProvider({ webhookUrl })).

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { setProvider } from '@molecule/api-notifications'
import { provider } from '@molecule/api-notifications-slack'

setProvider('slack', provider)

Type

provider

Installation

npm install @molecule/api-notifications-slack @molecule/api-notifications @molecule/api-secrets

API

Interfaces

SlackConfig

Configuration for the Slack notifications provider.

interface SlackConfig {
  /** Slack incoming webhook URL. Defaults to NOTIFICATIONS_SLACK_WEBHOOK_URL env var. */
  webhookUrl?: string
  /** Request timeout in milliseconds. Defaults to 10000. */
  timeoutMs?: number
}

ProcessEnv

Environment variables consumed by the Slack notifications provider.

interface ProcessEnv {
  NOTIFICATIONS_SLACK_WEBHOOK_URL: string
}

Functions

createProvider(config)

Creates a Slack notifications provider.

function createProvider(config?: SlackConfig): NotificationsProvider
  • config — Optional configuration.

Returns: A NotificationsProvider that sends via Slack webhook.

Constants

provider

The provider implementation.

const provider: NotificationsProvider

notificationsSlackSecretDefinitions

Secret definitions required by the Slack notifications bond.

const notificationsSlackSecretDefinitions: SecretDefinition[]

Core Interface

Implements @molecule/api-notifications interface.

Injection Notes

Requirements

Peer dependencies:

  • @molecule/api-notifications ^1.0.1
  • @molecule/api-secrets ^1.0.1

Environment Variables

  • NOTIFICATIONS_SLACK_WEBHOOK_URL (required) — Slack incoming webhook URL
    • Setup: Create a Slack app → Incoming Webhooks → Add New Webhook to Workspace, then copy the URL.
    • Get it here: https://api.slack.com/apps
    • Example: https://hooks.slack.com/services/T00000000/B00000000/XXXX

Runtime Dependencies

  • @molecule/api-notifications

  • @molecule/api-secrets

  • send() never throws — it fails open. A missing webhook URL, a non-2xx from Slack, or a timeout (default 10 s) all resolve to { success: false, error }. If delivery matters, check result.success (or the per-channel results from the core notifyAll()); an unconfigured channel is otherwise silent.

  • The message is a single mrkdwn text field: *subject* newline body. Notification.metadata is not sent to Slack — bake anything the receiver needs into body.

  • The webhook URL and timeout are captured on first use (lazy) and frozen — env changes after the first send require a restart, or build a fresh instance via createProvider().

E2E Tests

Integration checklist — drive the real flow (no mocks), adapt each item to this app's actual events/triggers, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip:

  • Each ops/event trigger the app defines (service down, new signup, a threshold crossed) actually calls notifyAll() and the message reaches every bonded channel. The sandbox CAPTURES outbound notifications instead of sending — read them with the read_activity tool and confirm the subject+body match the event that fired. Never mock the flow or modify production code to expose it.
  • MULTI-CHANNEL: with >1 channel bonded, notifyAll() returns one NotificationResult per channel and a single channel failing (success: false) does not swallow the others — every other channel still captured, its own result still success: true.
  • The body carries the real event data (no undefined placeholders) and nothing that must not leave the system — no secrets, tokens, or PII that an external channel (Slack/webhook) should never receive.
  • Triggers are not end-user SPAMMABLE — no public endpoint lets a caller fire unbounded notifications; the trigger is internal (an ops/system event) or rate-limited.