Feature and documentation

Author: TheRealAgentK

AGENT.md

@@ -13,7 +13,7 @@
 ## Architecture
 - **CLI Tool**: Uploads sourcemaps, manages obfuscation symbols, tracks deployments for Raygun.com
 - **Main Entry**: `bin/raygun_cli.dart` - CLI argument parsing and command routing
-- **Commands**: `lib/src/` - Four main command modules: sourcemap, symbols, deployments, proguard
+- **Commands**: `lib/src/` - Five main command modules: sourcemap, symbols, deployments, proguard, dsym
 - **APIs**: Each command has corresponding API client (`*_api.dart`) for Raygun REST API calls
 - **Config**: `config_props.dart` handles arg parsing with env var fallbacks (RAYGUN_APP_ID, RAYGUN_TOKEN, RAYGUN_API_KEY)
 
@@ -311,6 +311,12 @@ dart run bin/raygun_cli.dart proguard \
   --path=mapping.txt \
   --external-access-token=EAT \
   --overwrite
+
+# iOS dSYM upload
+dart run bin/raygun_cli.dart dsym \
+  --app-id=XXX \
+  --path=path/to/dsym.zip \
+  --external-access-token=EAT
 ```
 
 ### Environment Variables

README.md

@@ -152,6 +152,44 @@ Response:
 
 ```
 
+#### iOS dSYM Uploader
+
+Upload dSYM files for iOS to [raygun.com](https://raygun.com).
+
+Documentation: https://raygun.com/documentation/language-guides/apple/crash-reporting/advanced-setup/#symbolication
+
+```
+raygun-cli dsym <arguments>
+```
+
+Minimal required arguments are:
+
+```
+raygun-cli dsym --app-id=APP_ID --path=<Path to dSYM zip file> --external-access-token=<EAT from your Raygun user account settings>
+```
+
+Example outputs:
+
+```
+Success:
+
+Uploading: <somewhere>/app.dSYM.zip
+Success uploading dSYM file: 200
+Result: {"Status":"Success","Message":"dSYM files uploaded"}
+
+Wrong External Access Token:
+
+Uploading: <somewhere>/app.dSYM.zip
+Error uploading dSYM file: 302
+Response: 
+
+Invalid dSYM file:
+
+Uploading: <somewhere>/invalid.zip
+Success uploading dSYM file: 200
+Result: {"Status":"Failure","Message":"No dSYM file found"}
+```
+
 #### Flutter obfuscation symbols
 
 Manages obfuscation symbols to [raygun.com](https://raygun.com).

bin/raygun_cli.dart

@@ -37,6 +37,10 @@ ArgParser buildParser() {
     ..addCommand(
       proguardCommand.name,
       proguardCommand.buildParser(),
+    )
+    ..addCommand(
+      dsymCommand.name,
+      dsymCommand.buildParser(),
     );
 }
 
@@ -95,6 +99,11 @@ void main(List<String> arguments) {
       return;
     }
 
+    if (results.command?.name == dsymCommand.name) {
+      dsymCommand.execute(results.command!, verbose);
+      return;
+    }
+
     throw FormatException('Unknown or missing command.');
   } on FormatException catch (e) {
     // Print usage information if an invalid argument was provided.

lib/raygun_cli.dart

@@ -1,4 +1,5 @@
 export 'src/deployments/deployments_command.dart';
+export 'src/dsym/dsym_command.dart';
 export 'src/proguard/proguard_command.dart';
 export 'src/sourcemap/sourcemap_command.dart';
 export 'src/symbols/symbols_command.dart';

lib/src/dsym/dsym.dart

@@ -0,0 +1,48 @@
+import 'package:raygun_cli/src/dsym/dsym_api.dart';
+import 'package:args/args.dart';
+import '../config_props.dart';
+
+class Dsym {
+  final ArgResults command;
+  final bool verbose;
+  final DsymApi api;
+
+  Dsym({
+    required this.command,
+    required this.verbose,
+    required this.api,
+  });
+
+  Future<bool> upload() async {
+    if (!command.wasParsed('path')) {
+      print('Error: Missing "--path"');
+      print('  Please provide "--path" via argument');
+      return false;
+    }
+
+    if (!command.wasParsed('external-access-token')) {
+      print('Error: Missing "--external-access-token"');
+      print('  Please provide "--external-access-token" via argument');
+      return false;
+    }
+
+    final externalAccessToken =
+        command.option('external-access-token') as String;
+    final path = command.option('path') as String;
+    final appId = ConfigProp.appId.load(command);
+
+    if (verbose) {
+      print('app-id: $appId');
+      print('external-access-token: $externalAccessToken');
+      print('path: $path');
+    }
+
+    final success = await api.uploadDsym(
+      appId: appId,
+      externalAccessToken: externalAccessToken,
+      path: path,
+    );
+
+    return success;
+  }
+}

lib/src/dsym/dsym_api.dart

@@ -0,0 +1,50 @@
+import 'dart:io';
+
+import 'package:http/http.dart' as http;
+import 'package:raygun_cli/src/core/raygun_api.dart';
+
+class DsymApi {
+  const DsymApi(this.httpClient);
+
+  final http.Client httpClient;
+
+  DsymApi.create() : httpClient = http.Client();
+
+  /// Uploads a dSYM zip file to Raygun.
+  /// Returns true if the upload was successful.
+  Future<bool> uploadDsym({
+    required String appId,
+    required String externalAccessToken,
+    required String path,
+  }) async {
+    final file = File(path);
+    if (!file.existsSync()) {
+      print('$path: file not found!');
+      return false;
+    }
+    print('Uploading: $path');
+
+    final request = RaygunMultipartRequestBuilder(
+      'https://app.raygun.com/dashboard/$appId/settings/symbols?authToken=$externalAccessToken',
+      'POST',
+    ).addFile('DsymFile', path).build();
+
+    try {
+      final response = await httpClient.send(request);
+      final responseBody = await response.stream.bytesToString();
+
+      if (response.statusCode == 200) {
+        print('Success uploading dSYM file: ${response.statusCode}');
+        print('Result: $responseBody');
+        return true;
+      }
+
+      print('Error uploading dSYM file: ${response.statusCode}');
+      print('Response: $responseBody');
+      return false;
+    } catch (e) {
+      print('Exception while uploading dSYM file: $e');
+      return false;
+    }
+  }
+}

lib/src/dsym/dsym_command.dart

@@ -0,0 +1,67 @@
+import 'dart:io';
+
+import 'package:args/args.dart';
+import 'package:raygun_cli/src/core/raygun_command.dart';
+import 'package:raygun_cli/src/dsym/dsym.dart';
+import 'package:raygun_cli/src/dsym/dsym_api.dart';
+
+final DsymCommand dsymCommand = DsymCommand(api: DsymApi.create());
+
+class DsymCommand extends RaygunCommand {
+  const DsymCommand({required this.api});
+
+  final DsymApi api;
+
+  @override
+  String get name => 'dsym';
+
+  @override
+  ArgParser buildParser() {
+    return ArgParser()
+      ..addFlag(
+        'help',
+        abbr: 'h',
+        negatable: false,
+        help: 'Print dsym usage information',
+      )
+      ..addOption(
+        'app-id',
+        mandatory: true,
+        help: 'Raygun application ID',
+      )
+      ..addOption(
+        'external-access-token',
+        mandatory: true,
+        help: 'Raygun external access token',
+      )
+      ..addOption(
+        'path',
+        mandatory: true,
+        help: 'Path to the dSYM zip file',
+      );
+  }
+
+  @override
+  void execute(ArgResults command, bool verbose) {
+    if (command.wasParsed('help')) {
+      print('Usage: raygun-cli $name <arguments>');
+      print(buildParser().usage);
+      exit(0);
+    }
+
+    Dsym(
+      command: command,
+      verbose: verbose,
+      api: api,
+    ).upload().then((success) {
+      if (success) {
+        exit(0);
+      } else {
+        exit(1);
+      }
+    }).catchError((error) {
+      print('Error uploading dSYM file: $error');
+      exit(2);
+    });
+  }
+}