[Span First #2]: Add envelope type to Dart layer

packages/dart/lib/src/sentry_envelope.dart

@@ -104,30 +104,32 @@ class SentryEnvelope {
   factory SentryEnvelope.fromLogsData(
     List<List<int>> encodedLogs,
     SdkVersion sdkVersion,
-  ) {
-    // Create the payload in the format expected by Sentry
-    // Format: {"items": [log1, log2, ...]}
-    final builder = BytesBuilder(copy: false);
-    builder.add(utf8.encode('{"items":['));
-    for (int i = 0; i < encodedLogs.length; i++) {
-      if (i > 0) {
-        builder.add(utf8.encode(','));
-      }
-      builder.add(encodedLogs[i]);
-    }
-    builder.add(utf8.encode(']}'));
-
-    return SentryEnvelope(
-      SentryEnvelopeHeader(
-        null,
-        sdkVersion,
-      ),
-      [
-        SentryEnvelopeItem.fromLogsData(
-            builder.takeBytes(), encodedLogs.length),
-      ],
-    );
-  }
+  ) =>
+      SentryEnvelope(
+        SentryEnvelopeHeader(null, sdkVersion),
+        [
+          SentryEnvelopeItem.fromLogsData(
+              _buildItemsPayload(encodedLogs), encodedLogs.length)
+        ],
+      );
+
+  /// Create a [SentryEnvelope] containing raw span data payload.
+  /// This is used by the span buffer to send pre-encoded spans.
+  @internal
+  factory SentryEnvelope.fromSpansData(
+    List<List<int>> encodedSpans,
+    SdkVersion sdkVersion, {
+    String? dsn,
+    SentryTraceContextHeader? traceContext,
+  }) =>
+      SentryEnvelope(
+        SentryEnvelopeHeader(null, sdkVersion,
+            dsn: dsn, traceContext: traceContext),
+        [
+          SentryEnvelopeItem.fromSpansData(
+              _buildItemsPayload(encodedSpans), encodedSpans.length)
+        ],
+      );
 
   /// Stream binary data representation of `Envelope` file encoded.
   Stream<List<int>> envelopeStream(SentryOptions options) async* {
@@ -160,6 +162,20 @@ class SentryEnvelope {
     }
   }
 
+  /// Builds a payload in the format {"items": [item1, item2, ...]}
+  static Uint8List _buildItemsPayload(List<List<int>> encodedItems) {
+    final builder = BytesBuilder(copy: false);
+    builder.add(utf8.encode('{"items":['));
+    for (int i = 0; i < encodedItems.length; i++) {
+      if (i > 0) {
+        builder.add(utf8.encode(','));
+      }
+      builder.add(encodedItems[i]);
+    }
+    builder.add(utf8.encode(']}'));
+    return builder.takeBytes();
+  }
+
   /// Add an envelope item containing client report data.
   void addClientReport(ClientReport? clientReport) {
     if (clientReport != null) {

packages/dart/lib/src/sentry_envelope_item.dart

@@ -94,6 +94,21 @@ class SentryEnvelopeItem {
     );
   }
 
+  /// Create a [SentryEnvelopeItem] which holds pre-encoded span data.
+  /// This is used by the spans buffer to send pre-encoded spans.
+  @internal
+  factory SentryEnvelopeItem.fromSpansData(List<int> payload, int spansCount) {
+    return SentryEnvelopeItem(
+      SentryEnvelopeItemHeader(
+        SentryItemType.span,
+        itemCount: spansCount,
+        contentType: 'application/vnd.sentry.items.span.v2+json',
+      ),
+      () => payload,
+      originalObject: null,
+    );
+  }
+
   /// Header with info about type and length of data in bytes.
   final SentryEnvelopeItemHeader header;
 

packages/dart/lib/src/sentry_item_type.dart

@@ -6,5 +6,6 @@ class SentryItemType {
   static const String profile = 'profile';
   static const String statsd = 'statsd';
   static const String log = 'log';
+  static const String span = 'span';
   static const String unknown = '__unknown__';
 }

packages/dart/test/sentry_envelope_item_test.dart

@@ -134,6 +134,41 @@ void main() {
       expect(actualData, expectedData);
     });
 
+    test('fromSpansData', () async {
+      final span1 = jsonEncode({
+        'trace_id':
+            Sentry.currentHub.scope.propagationContext.traceId.toString(),
+        'span_id': SpanId.newId().toString(),
+        'name': 'GET /users',
+        'status': 'ok',
+        'is_segment': true,
+        'start_timestamp': 1742921669.158209,
+        'end_timestamp': 1742921669.180536,
+      });
+      final span2 = jsonEncode({
+        'trace_id':
+            Sentry.currentHub.scope.propagationContext.traceId.toString(),
+        'span_id': SpanId.newId().toString(),
+        'name': 'GET /posts',
+        'status': 'ok',
+        'is_segment': true,
+        'start_timestamp': 1742921669.158209,
+        'end_timestamp': 1742921669.180536,
+      });
+      final payload = utf8.encode('{"items":[$span1,$span2]');
+      final spansCount = 2;
+
+      final sut = SentryEnvelopeItem.fromSpansData(payload, spansCount);
+
+      expect(
+          sut.header.contentType, 'application/vnd.sentry.items.span.v2+json');
+      expect(sut.header.type, SentryItemType.span);
+      expect(sut.header.itemCount, spansCount);
+
+      final actualData = await sut.dataFactory();
+      expect(actualData, payload);
+    });
+
     test('fromLogsData', () async {
       final payload =
           utf8.encode('{"items":[{"test":"data1"},{"test":"data2"}]');

packages/dart/test/sentry_envelope_test.dart

@@ -173,6 +173,66 @@ void main() {
       expect(actualItemData, expectedItemData);
     });
 
+    test('fromSpansData', () async {
+      final span1 = utf8JsonEncoder.convert({
+        'trace_id':
+            Sentry.currentHub.scope.propagationContext.traceId.toString(),
+        'span_id': SpanId.newId().toString(),
+        'name': 'GET /users',
+        'status': 'ok',
+        'is_segment': true,
+        'start_timestamp': 1742921669.158209,
+        'end_timestamp': 1742921669.180536,
+      });
+      final span2 = utf8JsonEncoder.convert({
+        'trace_id':
+            Sentry.currentHub.scope.propagationContext.traceId.toString(),
+        'span_id': SpanId.newId().toString(),
+        'name': 'GET /posts',
+        'status': 'ok',
+        'is_segment': true,
+        'start_timestamp': 1742921669.158209,
+        'end_timestamp': 1742921669.180536,
+      });
+      final spansCount = 2;
+      final sdkVersion = SdkVersion(
+        name: 'fixture-name',
+        version: 'fixture-version',
+      );
+      final traceContext = SentryTraceContextHeader.fromJson(<String, dynamic>{
+        'trace_id': '${SentryId.newId()}',
+        'public_key': '123',
+      });
+
+      final sut = SentryEnvelope.fromSpansData([span1, span2], sdkVersion,
+          dsn: fakeDsn, traceContext: traceContext);
+
+      expect(sut.header.eventId, null);
+      expect(sut.header.sdkVersion, sdkVersion);
+      expect(sut.header.traceContext, traceContext);
+      expect(sut.header.dsn, fakeDsn);
+      expect(sut.items.length, 1);
+
+      final expectedEnvelopeItem = SentryEnvelopeItem.fromSpansData(
+        // The envelope should create the final payload with {"items": [...]} wrapper
+        utf8.encode('{"items":[') +
+            span1 +
+            utf8.encode(',') +
+            span2 +
+            utf8.encode(']}'),
+        spansCount,
+      );
+
+      expect(sut.items[0].header.contentType,
+          expectedEnvelopeItem.header.contentType);
+      expect(sut.items[0].header.type, expectedEnvelopeItem.header.type);
+      expect(sut.items[0].header.itemCount, spansCount);
+
+      final actualItem = await sut.items[0].dataFactory();
+      final expectedItem = await expectedEnvelopeItem.dataFactory();
+      expect(actualItem, expectedItem);
+    });
+
     test('fromLogsData', () async {
       final encodedLogs = [
         utf8.encode(