diff --git a/specs/001-export-telegram-members/contracts/export-api.yaml b/specs/001-export-telegram-members/contracts/export-api.yaml new file mode 100644 index 0000000..d25ff9c --- /dev/null +++ b/specs/001-export-telegram-members/contracts/export-api.yaml @@ -0,0 +1,59 @@ +# Export API Contract + +## Export Members Endpoint + +### Request +``` +POST /export +``` + +**Headers:** +- `Content-Type: application/json` + +**Body:** +```json +{ + "groupId": -1001234567890, + "outputFormat": "json", + "outputPath": "out/", + "includeUsernames": true, + "includePhoneNumbers": false +} +``` + +**Parameters:** +- `groupId` (int64, required): The Telegram group ID to export members from +- `outputFormat` (string, optional): Output format, default: "json" +- `outputPath` (string, optional): Output directory, default: "out/" +- `includeUsernames` (boolean, optional): Whether to include usernames, default: true +- `includePhoneNumbers` (boolean, optional): Whether to include phone numbers, default: false + +### Response + +**Success (200):** +```json +{ + "success": true, + "groupId": -1001234567890, + "groupName": "Example Group", + "memberCount": 150, + "outputFile": "out/example_group_members_20251206.json", + "exportTime": "2025-12-06T17:11:00Z" +} +``` + +**Error (400, 401, 403, 500):** +```json +{ + "success": false, + "error": "Error message describing the issue", + "code": "ERROR_CODE" +} +``` + +**Common Error Codes:** +- `AUTH_FAILED`: Authentication with Telegram failed +- `GROUP_NOT_FOUND`: Specified group ID doesn't exist or is inaccessible +- `INSUFFICIENT_PERMISSIONS`: User doesn't have permission to access group members +- `INVALID_GROUP_ID`: Group ID format is invalid +- `EXPORT_FAILED`: General failure during export process \ No newline at end of file diff --git a/specs/001-export-telegram-members/data-model.md b/specs/001-export-telegram-members/data-model.md new file mode 100644 index 0000000..0a0e3e3 --- /dev/null +++ b/specs/001-export-telegram-members/data-model.md @@ -0,0 +1,76 @@ +# Data Model: Telegram Group Members Export + +## Entity Definitions + +### GroupMember +**Description**: Represents a Telegram user within a group + +**Fields**: +- `ID` (int64): Unique user identifier from Telegram +- `Username` (string): User's Telegram username (may be empty) +- `FirstName` (string): User's first name +- `LastName` (string): User's last name (may be empty) +- `PhoneNumber` (string): User's phone number (restricted by privacy settings) +- `IsBot` (bool): Whether the user is a bot account +- `IsScam` (bool): Whether the user is marked as scam +- `IsFake` (bool): Whether the user is marked as fake + +**Validation Rules**: +- ID must be a positive integer +- FirstName cannot be empty (fallback to LastName if needed) + +### ExportConfiguration +**Description**: Settings that define the export parameters + +**Fields**: +- `APIID` (int): Telegram API ID from environment +- `APIHash` (string): Telegram API hash from environment +- `PhoneNumber` (string): Phone number for authentication +- `GroupID` (int64): Target group ID for member export +- `OutputDir` (string): Directory for output files (default: "out") +- `OutputFormat` (string): Output format (default: "json") +- `ProxyHost` (string): Optional proxy host +- `ProxyPort` (int): Optional proxy port +- `ProxySecret` (string): Optional proxy secret + +**Validation Rules**: +- APIID must be a positive integer +- APIHash must be a valid hex string +- PhoneNumber must be in international format +- GroupID must be a valid Telegram group ID + +### ExportResult +**Description**: Represents the result of an export operation + +**Fields**: +- `GroupID` (int64): The group ID that was exported +- `GroupName` (string): Name of the group (retrieved from Telegram) +- `MemberCount` (int): Number of members exported +- `OutputFilePath` (string): Path to the generated file +- `ExportTime` (time.Time): Timestamp of export completion +- `Success` (bool): Whether the export was successful +- `ErrorMessage` (string): Error message if export failed + +## State Transitions + +### Export Process States +1. **Initialization**: Configuration loaded and validated +2. **Authentication**: User authentication in progress +3. **Connecting**: Connection to Telegram established +4. **Retrieving**: Group members being retrieved +5. **Processing**: Members data being processed +6. **Exporting**: Data being written to file +7. **Completed**: Export finished successfully +8. **Failed**: Export process failed + +## Data Flow + +### Member Data Flow +``` +Telegram API → GroupMember entities → JSON serialization → Output file +``` + +### Configuration Data Flow +``` +Environment variables → ExportConfiguration → Telegram client → Export process +``` \ No newline at end of file diff --git a/specs/001-export-telegram-members/plan.md b/specs/001-export-telegram-members/plan.md new file mode 100644 index 0000000..8554bd5 --- /dev/null +++ b/specs/001-export-telegram-members/plan.md @@ -0,0 +1,68 @@ +# Implementation Plan: Export Telegram Group Members + +**Branch**: `001-export-telegram-members` | **Date**: 2025-12-06 | **Spec**: [link](spec.md) +**Input**: Feature specification from `/specs/001-export-telegram-members/spec.md` + +**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow. + +## Summary + +Implement a Go-based application that exports Telegram group members to a JSON file using the celestix/gotgproto library. The application will authenticate with Telegram using API credentials, retrieve member lists from specified groups using group IDs, and save the data in JSON format to an 'out' directory with a timestamped filename. The application will be contained in a single main.go file incorporating configuration and common functionality. + +## Technical Context + +**Language/Version**: Go 1.21 +**Primary Dependencies**: github.com/celestix/gotgproto, github.com/xelaj/mtproto, github.com/celestix/gotgproto/ext/handlers +**Storage**: File system (JSON output) +**Testing**: go test (built-in) +**Target Platform**: Cross-platform (Windows, Linux, macOS) +**Project Type**: Single Go application +**Performance Goals**: Export process completes within 5 minutes for groups with up to 10,000 members +**Constraints**: <500ms p95 for member retrieval, <200MB memory usage, must comply with Telegram's API terms of service +**Scale/Scope**: Single user application supporting export from multiple groups + +## Constitution Check + +*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* + +- [x] **Code Clarity**: Functions under 30 lines, nesting under 3 levels, descriptive names +- [x] **Minimal Dependencies**: Only essential libraries, justify each dependency +- [x] **Straightforward Flow**: Linear execution path, minimal nesting, early returns +- [x] **Explicit Configuration**: No magic numbers, clear environment variables +- [x] **Human-Readable Output**: Clear progress indicators, meaningful error messages + +*Post-design evaluation*: All constitution requirements continue to be met. The single-file architecture required by the specification maintains clarity through proper function separation and clear naming. Dependencies are minimal and all serve essential purposes for Telegram integration. + +## Project Structure + +### Documentation (this feature) + +```text +specs/001-export-telegram-members/ +├── plan.md # This file (/speckit.plan command output) +├── research.md # Phase 0 output (/speckit.plan command) +├── data-model.md # Phase 1 output (/speckit.plan command) +├── quickstart.md # Phase 1 output (/speckit.plan command) +├── contracts/ # Phase 1 output (/speckit.plan command) +└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan) +``` + +### Source Code (repository root) + +```text +main.go # Single Go file with all application logic +go.mod # Go module file +go.sum # Go dependencies checksum +.env.example # Example environment file +out/ # Output directory for generated JSON files (gitignored) +``` + +**Structure Decision**: Single Go application with all logic in main.go file as requested. Configuration, common utilities, and main logic are all contained in one file to simplify deployment and execution. + +## Complexity Tracking + +> **Fill ONLY if Constitution Check has violations that must be justified** + +| Violation | Why Needed | Simpler Alternative Rejected Because | +|-----------|------------|-------------------------------------| +| Single file architecture | Requirements specify single main.go file containing all logic | Splitting into multiple files would contradict explicit requirement | diff --git a/specs/001-export-telegram-members/quickstart.md b/specs/001-export-telegram-members/quickstart.md new file mode 100644 index 0000000..a30f894 --- /dev/null +++ b/specs/001-export-telegram-members/quickstart.md @@ -0,0 +1,103 @@ +# Quickstart: Telegram Group Members Export + +## Prerequisites + +- Go 1.21 or higher +- Telegram API credentials (API ID and API Hash) - obtain from https://my.telegram.org +- Phone number registered with Telegram + +## Setup + +1. **Get Telegram API credentials:** + - Visit https://my.telegram.org + - Login with your phone number + - Go to "API development tools" + - Create new application to get API ID and API Hash + +2. **Clone and setup the project:** + ```bash + git clone + cd + ``` + +3. **Create environment file:** + ```bash + cp .env.example .env + ``` + +4. **Configure environment variables:** + ```env + PHONE=+1234567890 # Your phone number in international format + API_ID=12345678 # Your Telegram API ID + API_HASH=your_api_hash # Your Telegram API Hash + GROUP_ID=-1001234567890 # Target group ID (negative for supergroups) + + # Optional proxy settings (if needed) + PROXY_HOST=proxy.example.com + PROXY_PORT=443 + PROXY_SECRET=your_secret + ``` + +## Building the Application + +```bash +go mod init telegram-exporter +go get github.com/celestix/gotgproto +go get github.com/xelaj/mtproto +go build -o telegram-exporter main.go +``` + +## Running the Application + +```bash +# Run the application (authentication code will be requested) +./telegram-exporter + +# Or run directly with Go +go run main.go +``` + +## Expected Output + +The application will: +1. Prompt for authentication code sent to your Telegram +2. Connect to the specified group +3. Export member information to `out/{groupname}_members_YYYYMMDD.json` +4. Display progress during the export process + +## Example Output File + +```json +{ + "groupId": -1001234567890, + "groupName": "Example Group", + "exportTime": "2025-12-06T17:11:00Z", + "memberCount": 150, + "members": [ + { + "id": 123456789, + "username": "example_user", + "firstName": "Example", + "lastName": "User" + }, + ... + ] +} +``` + +## Troubleshooting + +**Authentication Issues:** +- Ensure phone number is in international format (+1234567890) +- Verify API credentials are correct +- Check if phone number is properly registered with Telegram + +**Group Access Issues:** +- Verify the group ID is correct +- Ensure you have access to the group +- Confirm you're using the correct format (negative ID for supergroups) + +**Network Issues:** +- Check internet connection +- If behind firewall, try using proxy settings +- Verify API endpoints are not blocked in your region \ No newline at end of file diff --git a/specs/001-export-telegram-members/research.md b/specs/001-export-telegram-members/research.md new file mode 100644 index 0000000..27793f9 --- /dev/null +++ b/specs/001-export-telegram-members/research.md @@ -0,0 +1,68 @@ +# Research Summary: Telegram Group Members Export + +## Technology Research + +### Go Telegram Libraries +- **celestix/gotgproto**: A high-level Telegram client library for Go based on MTProto. Provides session management, authentication, and high-level API abstractions. +- **xelaj/mtproto**: Lower-level MTProto implementation that gotgproto is built on. Handles the protocol communication with Telegram's servers. +- **go-telegram/bot**: Alternative library but focuses on bot API rather than user accounts, which is not suitable for this use case. + +### Alternative Libraries Comparison +- **Telethon (Python)**: The current Python implementation uses Telethon which provides easy access to Telegram's user API. +- **go-telegram-bot-api**: Only supports bot API, not suitable for accessing group members. +- **gotd/td**: Another Go MTProto client library, but more complex to use than gotgproto. + +**Decision**: Use `celestix/gotgproto` as it provides the highest level of abstraction while still supporting user account authentication and group member access. + +### Authentication Flow +The authentication flow in gotgproto requires: +1. Initial connection with API ID and hash +2. Sending authentication code request to phone number +3. User input of received code +4. Optional 2FA password if enabled + +### Group Access by ID +- Telegram groups can be accessed directly by their numeric group ID (chat ID) +- This is more reliable than group names which can change +- Group IDs can be positive or negative numbers (negative for supergroups/channels) + +## Data Model Research + +### Member Information Fields +Based on the Python implementation, the following member fields are accessible: +- `id`: Unique user identifier (int64) +- `username`: User's username (string, may be empty) +- `first_name`: User's first name (string) +- `last_name`: User's last name (string, may be empty) + +### File Output Format +- JSON output format is required per specification +- Output directory should be "out" in current working directory +- Filename format: `{groupname}_members_{YYYYMMDD}.json` +- Since we're using group ID instead of name, the filename will use the group ID + +## Error Handling Patterns + +### Common Error Scenarios +- Authentication failures (invalid API credentials, incorrect code) +- Rate limiting by Telegram +- Permission errors (insufficient privileges to access group) +- Network connectivity issues +- Invalid group ID + +### Error Handling Strategy +- Implement proper error wrapping with context +- Provide user-friendly error messages +- Graceful degradation where possible + +## Performance Considerations + +### Large Group Handling +- For groups with many members, pagination will be handled automatically by the library +- Progress indicators needed for large exports +- Memory management for large datasets + +### Best Practices from Python Implementation +- Sort members by ID for consistent output +- Handle special characters in group names for file paths +- Create output directory if it doesn't exist \ No newline at end of file