Event Notifications (events)

Relevant source files

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

• src/commands/events.ts
• src/internal/command.ts
• src/i18n/catalog/en.ts
• src/test-support/command-path-mocks.ts
• src/command-paths.test.ts
• src/internal/cli-contract.ts

The events module provides functionality to list and filter account history events within the put.io ecosystem. It serves as a diagnostic and monitoring tool, allowing users and automated agents to track activities such as file uploads, transfer completions, and system notifications.

The module is built using the Effect framework and integrates with the put.io SDK to fetch historical data. It supports standard CLI features including field selection, pagination via record limits, and client-side type filtering.

Sources: src/commands/events.ts:1-77, src/i18n/catalog/en.ts:251-260

Architecture and Command Logic

The event system is structured around the events list command. This command coordinates several internal services to resolve authentication, fetch data from the API, apply local filters, and format the output for the user.

Execution Flow

When a user executes putio events list, the system follows a structured pipeline:

1. Control Resolution: Resolves output modes (JSON, Text, NDJSON) and validates field selection flags.
2. API Interaction: Uses an authenticated SDK instance to call the sdk.events.list method.
3. Local Filtering: Applies client-side filtering based on the --type flag if provided.
4. Output Rendering: Passes the filtered results to the output service, which uses specialized terminal renderers or standard JSON serializers.

The diagram shows the logic flow from user input to the final rendering of event data.
Sources: src/commands/events.ts:44-77, src/internal/command.ts:384-406

Command Options and Configuration

The events list command accepts several flags to narrow down the history and customize the display.

Input Flags

Flag	Type	Description
--before	Integer	Filters events occurring before a specific event ID.
--per-page	Integer	Limits the number of events returned per request (Default: 20).
--type	Choice	Filters events by a specific event type (e.g., upload, transfer_completed).
--fields	String	Comma-separated list of top-level fields to include in JSON output.
--output	Choice	Selects the output format: json, text, or ndjson.

Sources: src/commands/events.ts:18-35, src/commands/events.ts:88-92, src/internal/command.ts:22-26

Supported Event Types

The CLI supports a specific set of event types for filtering:

• file_shared, upload, zip_created
• transfer_completed, transfer_error, transfer_from_rss_error, transfer_callback_error
• file_from_rss_deleted_for_space, private_torrent_pin, rss_filter_paused
• voucher

Sources: src/commands/events.ts:20-32

Data Models

The event data structure represents various actions performed on an account. While the SDK handles the raw response, the CLI interacts with objects containing the following core fields:

Field	Type	Description
id	Number	Unique identifier for the event.
type	String	The category of the event (e.g., transfer_completed).
created_at	String	ISO 8601 timestamp of the event.
transfer_name	String	(Optional) Name of the transfer involved.
file_name	String	(Optional) Name of the file involved.

Sources: src/test-support/command-path-mocks.ts:24-38, src/command-paths.test.ts:98-112

Implementation Details

Event Filtering Logic

Filtering is performed client-side using the filterEventsByType function. This ensures that even if the API returns a broader set of events, the CLI output remains focused on the user's request.

export const filterEventsByType = <
  A extends {
    readonly type: string;
  },
>(
  events: ReadonlyArray<A>,
  expectedType: string | undefined,
) => events.filter((event) => (expectedType ? event.type === expectedType : true));

Sources: src/commands/events.ts:37-43

Integration with UI and Localization

The module uses a centralized translation service for terminal messaging, ensuring consistent feedback during data loading and summary rendering.

• Loading Message: "Loading events..."
• Empty State: "No events found."
• Summary: "Showing {{count}} event(s)."

Sources: src/i18n/catalog/en.ts:251-260, src/commands/events.ts:55

Conclusion

The events module provides a streamlined interface for auditing account activity. By combining robust SDK integration with client-side filtering and flexible output modes, it enables both human users and automated systems to efficiently monitor the state and history of their put.io account.