Molecule.dev

@molecule/api-channel-capture

Provider bond · channel · API (Node) · v1.0.3 · Apache-2.0

Channel capture provider for molecule.dev

npm install @molecule/api-channel-capture

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

How it works

@molecule/api-channel-capture is a provider bond on the API (Node) side: it implements the channel core interface (@molecule/api-channel) 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-channel'
import { provider } from '@molecule/api-channel-capture'

setProvider(provider)

Works with: @molecule/api-activity, @molecule/api-channel

Reference

Channel capture provider for molecule.dev.

Records every sendMessage() call as an activity event. Intercept-only by default; delegates + tees when wrapping a real provider.

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-channel'
import { provider } from '@molecule/api-channel-capture'

setProvider(provider)

Type

provider

Installation

npm install @molecule/api-channel-capture @molecule/api-activity @molecule/api-channel

API

Functions

createChannelCaptureProvider(realProvider)

Creates a channel capture provider.

When realProvider is provided, each message is posted through it and the captured event records the real outcome (delegate + tee). When omitted (the dev default), messages are intercepted and a synthetic SendResult is returned. Inbound / signature / feature methods delegate to the real provider when present and otherwise return intercept-only defaults.

function createChannelCaptureProvider(realProvider?: ChannelProvider): ChannelProvider
  • realProvider — Optional real provider to delegate to and tee.

Returns: A ChannelProvider that records activity for every send.

Constants

provider

Default channel capture provider (intercept-only).

const provider: ChannelProvider

Core Interface

Implements @molecule/api-channel interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/api-channel'
import { provider } from '@molecule/api-channel-capture'

export function setupChannelCapture(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

  • @molecule/api-activity ^1.0.1
  • @molecule/api-channel ^1.0.1

Runtime Dependencies

  • @molecule/api-activity

  • @molecule/api-channel

  • Two modes, and the choice decides whether the message is POSTED. INTERCEPT-ONLY (provider, or createChannelCaptureProvider() with no argument) records the message and returns a synthetic success — nothing reaches the channel. DELEGATE + TEE (createChannelCaptureProvider(real)) posts through the real provider AND records the real outcome. Anywhere real messages must go out (production), wrap the real provider — never bond the intercept-only provider.

  • Recording is best-effort: a bonded ActivitySink that throws NEVER changes the outcome of sendMessage() — a successful real post still resolves and a failed one still rejects with the REAL provider error.

  • Bond an activity sink or captures vanish. Captured sends are delivered via @molecule/api-activity's record(), which silently no-ops when no sink is bonded. Wire one at startup (e.g. @molecule/api-activity-console or -http) before this provider, or every intercepted message is dropped with no trace.

  • Intercept-only mode (no realProvider) returns a synthetic success from sendMessage(), always fails verifyWebhookSignature() (false), and parseInbound() returns a stub — inbound webhook flows need a real provider wrapped via createChannelCaptureProvider(realProvider).

E2E Tests

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

  • Each channel-notifying flow the app defines (a Slack/Discord alert on a new order, a status-change message) actually produces a message. The sandbox CAPTURES channel messages instead of sending — read them with the read_activity tool (filter type 'channel'); never mock the flow or modify production code to expose the message.
  • The captured message targets the configured channel/provider name and carries the app's real content (readable text, no undefined placeholders, no secrets).
  • A failed send (unbonded or misconfigured provider) is visible in logs/UI — never silently swallowed.