CLI: Analytics
Relevant source files
The following files were used as context for generating this wiki page:
The analytics CLI is a command-line interface for newsletter analytics and reporting. It provides tools to generate reports on subscriber growth, newsletter performance, and user engagement. The CLI acts as a user-friendly frontend to the AnalyticsManager, which contains the core logic for processing and aggregating data. All data is stored in a file-based system, primarily analytics.json.
This tool is part of a larger suite of CLI tools for managing the newsletter, including Subscriber Management and Secure Data Export.
Sources: newsletter-program/src/cli/analytics-cli.js:4-6, newsletter-program/README-SUBSCRIBER-MANAGEMENT.md:7-15
Architecture
The analytics system is composed of two main components: the CLI and the Manager. The CLI is responsible for command parsing and presenting data, while the Manager handles data loading, processing, and report generation. It interacts with the SubscriberFileManager to access subscriber data and reads/writes to analytics.json for event and newsletter send data.
Sources: newsletter-program/src/cli/analytics-cli.js:4-5, newsletter-program/src/core/analytics-manager.js:5-8, newsletter-program/README-SUBSCRIBER-MANAGEMENT.md:17-26
Component Interaction
The following diagram illustrates the interaction between the user, the CLI, the core manager, and the data files.
This diagram shows how analytics-cli.js orchestrates calls to AnalyticsManager, which in turn gathers data from multiple sources to build reports.
Sources: newsletter-program/src/cli/analytics-cli.js:4-5, newsletter-program/src/core/analytics-manager.js:5-8
Data Models
The analytics system relies on two primary data models stored within analytics.json: newsletters and events.
Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md:40-52, 211-236
Analytics Data Schema
The analytics.json file contains two main arrays: newsletters for tracking sent campaigns and events for tracking subscriber activities.
This ER diagram shows the structure of the analytics.json file.
Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md:211-236, newsletter-program/src/core/analytics-manager.js:18-24
Newsletter Record
This object stores performance metrics for each newsletter sent.
| Field | Type | Description |
|---|---|---|
id | string | A unique identifier for the newsletter send event. |
subject | string | The subject line of the newsletter. |
sentAt | string | ISO 8601 timestamp of when the newsletter was sent. |
recipientCount | number | Total number of recipients. |
successCount | number | Number of successful deliveries. |
failureCount | number | Number of failed deliveries. |
source | string | The trigger for the send (e.g., manual, rss, scheduled). |
Sources: newsletter-program/src/core/analytics-manager.js:60-69, newsletter-program/README-SUBSCRIBER-MANAGEMENT.md:220-229
Analytics Event
This object logs key subscriber actions.
| Field | Type | Description |
|---|---|---|
id | string | A unique identifier for the event. |
type | string | The type of event (e.g., subscribe, unsubscribe, bounce, update). |
timestamp | string | ISO 8601 timestamp of the event. |
subscriberId | string | The ID of the subscriber associated with the event. |
email | string | The subscriber's email (encrypted in storage). |
source | string | The source of the subscriber (e.g., website, import). |
Sources: newsletter-program/src/core/analytics-manager.js:80-89, newsletter-program/README-SUBSCRIBER-MANAGEMENT.md:40-52
CLI Commands
The analytics CLI is invoked via npm run analytics. It provides several commands for reporting, data management, and export.
Sources: newsletter-program/package.json:15, newsletter-program/src/cli/analytics-cli.js:10-12
| Command | Description |
|---|---|
dashboard | Shows a high-level analytics dashboard. |
growth | Generates a subscriber growth report. |
newsletters | Generates a newsletter performance report. |
engagement | Generates a subscriber engagement report. |
export | Exports analytics data to JSON or CSV. |
record-send | Manually records a newsletter send event. |
clean | Cleans old analytics data. |
Sources: newsletter-program/src/cli/analytics-cli.js, newsletter-program/README-SUBSCRIBER-MANAGEMENT.md:120-146
dashboard
Displays a quick overview of key metrics from the last 7 days, including subscriber growth, newsletter performance, and engagement. It aggregates data from the other reporting commands.
Usage:
npm run analytics dashboard
Sources: newsletter-program/src/cli/analytics-cli.js:316-361
growth
Generates a report on subscriber growth over a specified period. The output includes total subscriptions, unsubscriptions, net growth, and a daily breakdown.
| Option | Alias | Description | Default |
|---|---|---|---|
--days <days> | -d | Number of days to analyze. | 30 |
--format <format> | Output format (table or json). | table | |
--output <file> | -o | Save the detailed JSON report to a file. | N/A |
Usage:
npm run analytics growth --days 30
Data Flow:
This sequence shows how the growth command gathers data from both subscriber and analytics files to generate its report.
Sources: newsletter-program/src/cli/analytics-cli.js:16-72, newsletter-program/src/core/analytics-manager.js:106-160
newsletters
Generates a report on the performance of sent newsletters, including delivery rates and performance broken down by source.
| Option | Alias | Description | Default |
|---|---|---|---|
--days <days> | -d | Number of days to analyze. | 30 |
--format <format> | Output format (table or json). | table | |
--output <file> | -o | Save the detailed JSON report to a file. | N/A |
Usage:
npm run analytics newsletters --days 30
Sources: newsletter-program/src/cli/analytics-cli.js:75-139, newsletter-program/src/core/analytics-manager.js:163-221
engagement
Generates a report on subscriber engagement, including active subscriber counts, churn rate, and breakdowns by source and preferences.
| Option | Alias | Description | Default |
|---|---|---|---|
--format <format> | Output format (table or json). | table | |
--output <file> | -o | Save the detailed JSON report to a file. | N/A |
Usage:
npm run analytics engagement
Sources: newsletter-program/src/cli/analytics-cli.js:142-206, newsletter-program/src/core/analytics-manager.js:224-282
export
Exports raw analytics data. This can be used for backups or for analysis in external tools.
| Option | Alias | Description | Default |
|---|---|---|---|
--format <format> | -f | Export format (json or csv). | json |
--output <file> | -o | Output file path. | analytics-export-YYYY-MM-DD.json |
Usage:
npm run analytics export --format csv --output analytics.csv
Sources: newsletter-program/src/cli/analytics-cli.js:209-226, newsletter-program/src/core/analytics-manager.js:285-325
record-send
Manually records a newsletter send event. This is useful for tracking sends that occur outside of an automated workflow.
| Option | Alias | Description |
|---|---|---|
--subject <subject> | -s | Required. Newsletter subject. |
--recipients <count> | -r | Required. Number of recipients. |
--success <count> | Number of successful sends. | |
--failures <count> | Number of failed sends. | |
--source <source> | Newsletter source (e.g., manual). |
Usage:
npm run analytics record-send --subject "Weekly Update" --recipients 100 --success 98
Sources: newsletter-program/src/cli/analytics-cli.js:229-258, newsletter-program/src/core/analytics-manager.js:57-73
clean
A maintenance command to remove old analytics data from analytics.json, helping to keep the file size manageable.
| Option | Alias | Description | Default |
|---|---|---|---|
--days <days> | -d | Number of days of data to keep. | 365 |
--confirm | Confirm cleanup without a prompt. | false |
Usage:
npm run analytics clean --days 180 --confirm
Workflow:
This flowchart shows the process for the clean command, including the safety check for confirmation.