CLI: Subscriber Management
Relevant source files
The following files were used as context for generating this wiki page:
- newsletter-program/src/cli/subscriber-cli.js
- newsletter-program/src/core/subscriber-file-manager.js
- newsletter-program/README-SUBSCRIBER-MANAGEMENT.md
- newsletter-program/src/core/subscriber-file-manager.test.js
- newsletter-program/package.json
- newsletter-program/src/cli/analytics-cli.js
- newsletter-program/src/core/analytics-manager.js
The Subscriber Management CLI is a command-line tool for managing the encrypted, file-based subscriber list for the newsletter program. It provides a comprehensive set of commands for all subscriber-related operations, including adding, listing, updating, and removing subscribers, as well as performing maintenance tasks like data validation, optimization, and exporting. The system is designed with security in mind, encrypting all subscriber emails at rest and providing GDPR-compliant features.
This tool is a key part of the larger newsletter system, which also includes CLIs for Newsletter Composition and Analytics & Reporting. It interacts directly with the core SubscriberFileManager to manipulate the encrypted data file.
Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md, newsletter-program/src/cli/subscriber-cli.js
Architecture
The subscriber management system is built on a simple, file-based architecture, eliminating the need for external database dependencies. The CLI (subscriber-cli.js) acts as the user interface, delegating all business logic to the SubscriberFileManager class. This manager handles all interactions with the encrypted data file, including encryption, decryption, and file I/O.
Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md, newsletter-program/src/cli/subscriber-cli.js:13
The following diagram illustrates the high-level architecture of the subscriber management components.
Core Component: SubscriberFileManager
The SubscriberFileManager class is the central component for all subscriber data operations. It encapsulates the logic for file handling, data encryption/decryption, and subscriber lifecycle management.
Data Storage & Encryption
All subscriber data is stored in a single JSON file located at newsletter-program/src/data/subscribers.encrypted.json. To ensure privacy, subscriber email addresses within this file are encrypted using AES-256-CBC. The encryption key is managed via the ENCRYPTION_KEY environment variable.
Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md, newsletter-program/src/core/subscriber-file-manager.js:6-9
Subscriber Data Model
The following diagram shows the structure of a subscriber record. The email field is stored in its encrypted form (encryptedEmail) in the JSON file.
CLI Commands
The subscriber-cli.js script, aliased as npm run subscribers, provides several commands to manage the subscriber list.
Sources: newsletter-program/package.json:16, newsletter-program/src/cli/subscriber-cli.js
add
Adds a new subscriber to the encrypted file. It automatically generates a unique ID and an unsubscribe token.
Usage
npm run subscribers add --email <email> [options]
Options
| Option | Alias | Description | Default |
|---|---|---|---|
--email <email> | -e | Subscriber's email address. | (Required) |
--source <source> | -s | The source of the subscription. | cli |
--frequency <frequency> | -f | Email frequency preference. | weekly |
--topics <topics> | -t | Comma-separated list of topics. | [] |
The following sequence diagram shows the flow for adding a new subscriber.
list
Lists all subscribers, with options to filter the results and change the output format.
Usage
npm run subscribers list [options]
Options
| Option | Alias | Description | Default |
|---|---|---|---|
--status <status> | -s | Filter by status (active, unsubscribed, bounced). | - |
--source <source> | Filter by subscription source. | - | |
--frequency <frequency> | -f | Filter by frequency preference. | - |
--format <format> | Output format (table, json). | table |
Sources: newsletter-program/src/cli/subscriber-cli.js:51-93
update
Updates an existing subscriber's information, identified by their ID.
Usage
npm run subscribers update --id <id> [options]
Options
| Option | Alias | Description |
|---|---|---|
--id <id> | -i | The ID of the subscriber to update. (Required) |
--status <status> | -s | New status (active, unsubscribed, bounced). |
--frequency <frequency> | -f | New frequency preference. |
--topics <topics> | -t | New comma-separated list of topics. |
Sources: newsletter-program/src/cli/subscriber-cli.js:96-123
remove
Removes a subscriber from the list. Requires a confirmation flag for safety.
Usage
npm run subscribers remove --id <id> --confirm
Options
| Option | Alias | Description |
|---|---|---|
--id <id> | -i | The ID of the subscriber to remove. (Required) |
--confirm | Confirms the deletion without a prompt. (Required) |
Sources: newsletter-program/src/cli/subscriber-cli.js:126-150
stats
Displays aggregate statistics about the subscriber base, such as total counts by status, source, and frequency.
Usage
npm run subscribers stats
This command retrieves and formats data from the getStats method in SubscriberFileManager.
Sources: newsletter-program/src/cli/subscriber-cli.js:153-181, newsletter-program/src/core/subscriber-file-manager.js:275-312
export
Exports subscriber data to a file in various formats.
Usage
npm run subscribers export [options]
Options
| Option | Alias | Description | Default |
|---|---|---|---|
--format <format> | -f | Export format (json, csv, txt). | json |
--output <file> | -o | Path to the output file. | subscribers-export-YYYY-MM-DD.<ext> |
--status <status> | -s | Filter exported subscribers by status. | - |
--exclude-metadata | Exclude metadata fields from the export. | false |
Sources: newsletter-program/src/cli/subscriber-cli.js:184-207, newsletter-program/src/core/subscriber-file-manager.js:315-378
import
Imports subscribers from a JSON, CSV, or TXT file.
Usage
npm run subscribers import --file <file> [options]
Options
| Option | Alias | Description | Default |
|---|---|---|---|
--file <file> | -f | Path to the input file. (Required) | - |
--format <format> | Import format (json, csv, txt). | json | |
--allow-duplicates | Allow importing subscribers with existing email addresses. | false |
Sources: newsletter-program/src/cli/subscriber-cli.js:210-241, newsletter-program/src/core/subscriber-file-manager.js:381-449
File Maintenance Commands
These commands are used for maintaining the health and security of the subscriber data file.
validate
Checks the integrity of the subscribers.encrypted.json file. It verifies the file structure, checks for missing fields in subscriber records, and reports duplicate emails.
Usage
npm run subscribers validate
Sources: newsletter-program/src/cli/subscriber-cli.js:244-276, newsletter-program/src/core/subscriber-file-manager.js:452-500
optimize
Optimizes the subscriber file by removing duplicate entries, keeping the most recently subscribed record for each email address.
Usage
npm run subscribers optimize --confirm
Sources: newsletter-program/src/cli/subscriber-cli.js:279-299, newsletter-program/src/core/subscriber-file-manager.js:503-523
rotate-key
This command is intended to re-encrypt all data with a new encryption key. However, the underlying functionality is not yet implemented.
Usage
npm run subscribers rotate-key --confirm
Note: Executing this command will currently throw an error stating that key rotation is not implemented.
Sources: newsletter-program/src/cli/subscriber-cli.js:302-322, newsletter-program/src/core/subscriber-file-manager.js:548-552