Notifications System

Relevant source files

The following files were used as context for generating this wiki page:

• src/commands/notifications.ts
• tests/commands/notifications.test.ts
• src/client.ts
• src/bin.ts
• src/output.ts
• CLAUDE.md

The Notifications System within the Recoup CLI provides a streamlined interface for sending email notifications directly to account owners. The system is designed to automatically resolve the recipient based on the provided API key, removing the need for a manual "To" address in standard use cases. It supports plain text, Markdown, and raw HTML bodies, along with advanced routing options like CC recipients and room associations.

The system acts as a thin wrapper around the Recoup REST API, specifically targeting the /api/notifications endpoint. It integrates with the broader CLI architecture by utilizing a centralized HTTP client and standardized output formatters for both human-readable console logs and machine-readable JSON.

Sources: src/commands/notifications.ts:6-8, CLAUDE.md:12-19

Architecture and Data Flow

The notifications system follows a modular command-based architecture. The notificationsCommand is defined using the commander library and is registered in the main CLI entry point.

Component Interaction

The CLI captures user input via command-line flags, constructs a request payload, and dispatches it through a centralized HTTP client. The client injects the necessary authentication headers before sending the request to the Recoup API.

The diagram above illustrates the request-response flow from the user terminal to the remote API.
Sources: src/bin.ts:1-30, src/client.ts:42-63, src/commands/notifications.ts:21-38

Sequence of Operation

When a user executes a notification command, the following sequence occurs:

1. Option Parsing: Commander validates required options (Subject).
2. Payload Construction: Optional parameters like HTML or CC are added to a body object.
3. API Request: The post function in the client sends a JSON payload to /api/notifications.
4. Output Rendering: Success messages or JSON results are printed based on the --json flag.

Command Options and API Parameters

The notifications command supports several flags that map directly to the API's JSON body.

Configuration Table

CLI Flag	API Field	Requirement	Description
--subject	subject	Required	The subject line of the email.
--text	text	Optional	Plain text or Markdown content.
--html	html	Optional	Raw HTML (takes precedence over text).
--cc	cc	Optional	CC recipient emails (can be repeated).
--room-id	room_id	Optional	ID for including a chat link in the footer.
--account	account_id	Optional	Targeted account ID (for organization keys).
--json	N/A	Optional	Switches output to raw JSON format.

Sources: src/commands/notifications.ts:9-16, tests/commands/notifications.test.ts:53-108

Implementation Details

Request Handling

The implementation utilizes the post helper from src/client.js. This helper ensures that the x-api-key (retrieved from the RECOUP_API_KEY environment variable) is included in every request. If the API returns a status of "error" or a non-200 HTTP code, the client throws an error that is caught by the command's action handler.

// src/commands/notifications.ts lines 21-31
    try {
      const body: Record<string, unknown> = {
        subject: opts.subject,
      };
      if (opts.text) body.text = opts.text;
      if (opts.html) body.html = opts.html;
      if (opts.cc && opts.cc.length > 0) body.cc = opts.cc;
      if (opts.roomId) body.room_id = opts.roomId;
      if (opts.account) body.account_id = opts.account;

      const data = await post("/api/notifications", body);

Sources: src/commands/notifications.ts:21-31, src/client.ts:42-63

Error Management

Errors are handled via a try-catch block that utilizes printError. This utility prints the error message to stderr and terminates the process with an exit code of 1. Common failures include missing API keys or failed recipient resolution at the API level.

Sources: src/output.ts:52-59, tests/commands/notifications.test.ts:145-155

Conclusion

The Notifications System provides a simple yet flexible way for developers and automated systems to trigger emails within the Recoup ecosystem. By leveraging the CLI's global configuration and shared HTTP client, it ensures consistent authentication and error handling while supporting both simple text alerts and complex HTML reporting.