fix(webAPI): Allow front channel embeds on TransmissionContent (#1276)

<!--- Provide a general summary of your changes in the Title above -->

## Description

* Adds missing XML comments for OpenAPI spec on transmissions
* Adds support for front channel embeds on transmission content
* Adds tests for transmission creation

<!--- Describe your changes in detail -->

## Related Issue(s)

- #1273 

## Verification

- [x] **Your** code builds clean without any errors or warnings
- [x] Manual testing done (required)
- [ ] Relevant automated test added (if you find this hard, leave it and
we'll help out)

## Documentation

- [ ] Documentation is updated (either in `docs`-directory, Altinnpedia
or a separate linked PR in
[altinn-studio-docs.](https://github.com/Altinn/altinn-studio-docs), if
applicable)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

## Summary by CodeRabbit

- **New Features**
- Added a new field `contentReference` to the `TransmissionContent`
type, allowing for additional content references.
- Enhanced various schemas with new properties, including
`contentReference` and improved descriptions for clarity.
- Introduced new properties in multiple DTOs to support dynamic content
embedding and improved data structure.

- **Bug Fixes**
- Updated validation rules for `mainContentReference` to ensure
compliance with specified constraints.

- **Tests**
- Added integration tests for the `Create` command in the ServiceOwner
feature to validate transmission creation functionality.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

docs/schema/V1/schema.verified.graphql

@@ -252,6 +252,7 @@ type Transmission {
 type TransmissionContent {
   title: ContentValue!
   summary: ContentValue!
+  contentReference: ContentValue
 }
 
 input SearchDialogInput {

src/Digdir.Domain.Dialogporten.Application/Features/V1/Common/Content/ContentValueDtoValidator.cs

@@ -78,5 +78,6 @@ DialogContentType.Values.MainContentReference when UserHasLegacyHtmlScope(user)
                 => contentType.AllowedMediaTypes.Append(MediaTypes.LegacyEmbeddableHtml).ToArray(),
             _ => contentType.AllowedMediaTypes
         };
-    private static bool UserHasLegacyHtmlScope(IUser? user) => user is not null && user.GetPrincipal().HasScope(Constants.LegacyHtmlScope);
+    private static bool UserHasLegacyHtmlScope(IUser? user)
+        => user is not null && user.GetPrincipal().HasScope(Constants.LegacyHtmlScope);
 }

src/Digdir.Domain.Dialogporten.Application/Features/V1/EndUser/DialogTransmissions/Queries/Get/GetDialogTransmissionDto.cs

@@ -99,6 +99,12 @@ public sealed class GetDialogTransmissionContentDto
     /// The summary of the content.
     /// </summary>
     public ContentValueDto Summary { get; set; } = null!;
+
+    /// <summary>
+    /// Front-channel embedded content. Used to dynamically embed content in the frontend from an external URL.
+    /// Allowed media types: application/vnd.dialogporten.frontchannelembed+json;type=markdown
+    /// </summary>
+    public ContentValueDto? ContentReference { get; set; }
 }
 
 public sealed class GetDialogTransmissionAttachmentDto

src/Digdir.Domain.Dialogporten.Application/Features/V1/EndUser/DialogTransmissions/Queries/Search/SearchDialogTransmissionDto.cs

@@ -8,49 +8,151 @@ namespace Digdir.Domain.Dialogporten.Application.Features.V1.EndUser.DialogTrans
 
 public sealed class SearchDialogTransmissionDto
 {
+    /// <summary>
+    /// The unique identifier for the transmission in UUIDv7 format.
+    /// </summary>
     public Guid Id { get; set; }
+
+    /// <summary>
+    /// The date and time when the transmission was created.
+    /// </summary>
     public DateTimeOffset CreatedAt { get; set; }
+
+    /// <summary>
+    /// The authorization attribute associated with the transmission.
+    /// </summary>
     public string? AuthorizationAttribute { get; set; }
+
+    /// <summary>
+    /// Flag indicating if the authenticated user is authorized for this transmission. If not, embedded content and
+    /// the attachments will not be available
+    /// </summary>
     public bool IsAuthorized { get; set; }
+
+    /// <summary>
+    /// The extended type URI for the transmission.
+    /// </summary>
     public Uri? ExtendedType { get; set; }
+
+    /// <summary>
+    /// The unique identifier for the related transmission, if any.
+    /// </summary>
     public Guid? RelatedTransmissionId { get; set; }
+
+    /// <summary>
+    /// The date and time when the transmission was deleted, if applicable.
+    /// </summary>
     public DateTimeOffset? DeletedAt { get; set; }
 
+    /// <summary>
+    /// The type of the transmission.
+    /// </summary>
     public DialogTransmissionType.Values Type { get; set; }
 
+    /// <summary>
+    /// The sender actor information for the transmission.
+    /// </summary>
     public SearchDialogTransmissionSenderActorDto Sender { get; set; } = null!;
 
+    /// <summary>
+    /// The content of the transmission.
+    /// </summary>
     public SearchDialogTransmissionContentDto Content { get; set; } = null!;
+
+    /// <summary>
+    /// The attachments associated with the transmission.
+    /// </summary>
     public List<SearchDialogTransmissionAttachmentDto> Attachments { get; set; } = [];
 }
 
 public sealed class SearchDialogTransmissionSenderActorDto
 {
+    /// <summary>
+    /// The unique identifier for the sender actor in UUIDv7 format.
+    /// </summary>
     public Guid Id { get; set; }
+
+    /// <summary>
+    /// The type of the actor.
+    /// </summary>
     public ActorType.Values ActorType { get; set; }
+
+    /// <summary>
+    /// The name of the actor.
+    /// </summary>
     public string ActorName { get; set; } = null!;
+
+    /// <summary>
+    /// The identifier of the actor.
+    /// </summary>
     public string ActorId { get; set; } = null!;
 }
 
 public sealed class SearchDialogTransmissionContentDto
 {
+    /// <summary>
+    /// The title of the content.
+    /// </summary>
     public ContentValueDto Title { get; set; } = null!;
+
+    /// <summary>
+    /// The summary of the content.
+    /// </summary>
     public ContentValueDto Summary { get; set; } = null!;
+
+    /// <summary>
+    /// Front-channel embedded content. Used to dynamically embed content in the frontend from an external URL.
+    /// Allowed media types: application/vnd.dialogporten.frontchannelembed+json;type=markdown
+    /// </summary>
+    public ContentValueDto? ContentReference { get; set; }
 }
 
 public sealed class SearchDialogTransmissionAttachmentDto
 {
+    /// <summary>
+    /// The unique identifier for the attachment in UUIDv7 format.
+    /// </summary>
     public Guid Id { get; set; }
 
+    /// <summary>
+    /// The display name of the attachment that should be used in GUIs.
+    /// </summary>
     public List<LocalizationDto> DisplayName { get; set; } = [];
+
+    /// <summary>
+    /// The URLs associated with the attachment, each referring to a different representation of the attachment.
+    /// </summary>
     public List<SearchDialogTransmissionAttachmentUrlDto> Urls { get; set; } = [];
 }
 
 public sealed class SearchDialogTransmissionAttachmentUrlDto
 {
+    /// <summary>
+    /// The unique identifier for the attachment URL in UUIDv7 format.
+    /// </summary>
     public Guid Id { get; set; }
+
+    /// <summary>
+    /// The fully qualified URL of the attachment. Will be set to "urn:dialogporten:unauthorized" if the user is
+    /// not authorized to access the transmission.
+    /// </summary>
+    /// <example>
+    /// https://someendpoint.com/someattachment.pdf
+    /// urn:dialogporten:unauthorized
+    /// </example>
     public Uri Url { get; set; } = null!;
+
+    /// <summary>
+    /// The media type of the attachment.
+    /// </summary>
+    /// <example>
+    /// application/pdf
+    /// application/zip
+    /// </example>
     public string? MediaType { get; set; } = null!;
 
+    /// <summary>
+    /// The type of consumer the URL is intended for.
+    /// </summary>
     public AttachmentUrlConsumerType.Values ConsumerType { get; set; }
 }

src/Digdir.Domain.Dialogporten.Application/Features/V1/EndUser/Dialogs/Queries/Get/GetDialogDto.cs

@@ -341,6 +341,12 @@ public sealed class GetDialogDialogTransmissionContentDto
     /// The transmission summary.
     /// </summary>
     public ContentValueDto Summary { get; set; } = null!;
+
+    /// <summary>
+    /// Front-channel embedded content. Used to dynamically embed content in the frontend from an external URL.
+    /// Allowed media types: application/vnd.dialogporten.frontchannelembed+json;type=markdown
+    /// </summary>
+    public ContentValueDto? ContentReference { get; set; }
 }
 
 public sealed class GetDialogDialogActivityDto

src/Digdir.Domain.Dialogporten.Application/Features/V1/ServiceOwner/DialogTransmissions/Queries/Get/GetDialogTransmissionDto.cs

@@ -93,6 +93,12 @@ public sealed class GetDialogTransmissionContentDto
     /// The summary of the content.
     /// </summary>
     public ContentValueDto Summary { get; set; } = null!;
+
+    /// <summary>
+    /// Front-channel embedded content. Used to dynamically embed content in the frontend from an external URL.
+    /// Allowed media types: application/vnd.dialogporten.frontchannelembed+json;type=markdown
+    /// </summary>
+    public ContentValueDto? ContentReference { get; set; }
 }
 
 public sealed class GetDialogTransmissionAttachmentDto

src/Digdir.Domain.Dialogporten.Application/Features/V1/ServiceOwner/DialogTransmissions/Queries/Search/SearchDialogTransmissionDto.cs

@@ -8,48 +8,144 @@ namespace Digdir.Domain.Dialogporten.Application.Features.V1.ServiceOwner.Dialog
 
 public sealed class SearchDialogTransmissionDto
 {
+    /// <summary>
+    /// The unique identifier for the transmission in UUIDv7 format.
+    /// </summary>
     public Guid Id { get; set; }
+
+    /// <summary>
+    /// The date and time when the transmission was created.
+    /// </summary>
     public DateTimeOffset CreatedAt { get; set; }
+
+    /// <summary>
+    /// The authorization attribute associated with the transmission.
+    /// </summary>
     public string? AuthorizationAttribute { get; set; }
+
+    /// <summary>
+    /// The extended type URI for the transmission.
+    /// </summary>
     public Uri? ExtendedType { get; set; }
+
+    /// <summary>
+    /// The unique identifier for the related transmission, if any.
+    /// </summary>
     public Guid? RelatedTransmissionId { get; set; }
+
+    /// <summary>
+    /// The date and time when the transmission was deleted, if applicable.
+    /// </summary>
     public DateTimeOffset? DeletedAt { get; set; }
 
+    /// <summary>
+    /// The type of the transmission.
+    /// </summary>
     public DialogTransmissionType.Values Type { get; set; }
 
+    /// <summary>
+    /// The sender actor information for the transmission.
+    /// </summary>
     public SearchDialogTransmissionSenderActorDto Sender { get; set; } = null!;
 
+    /// <summary>
+    /// The content of the transmission.
+    /// </summary>
     public SearchDialogTransmissionContentDto Content { get; set; } = null!;
+
+    /// <summary>
+    /// The attachments associated with the transmission.
+    /// </summary>
     public List<SearchDialogTransmissionAttachmentDto> Attachments { get; set; } = [];
 }
 
 public sealed class SearchDialogTransmissionSenderActorDto
 {
+    /// <summary>
+    /// The unique identifier for the sender actor in UUIDv7 format.
+    /// </summary>
     public Guid Id { get; set; }
+
+    /// <summary>
+    /// The type of the actor.
+    /// </summary>
     public ActorType.Values ActorType { get; set; }
+
+    /// <summary>
+    /// The name of the actor.
+    /// </summary>
     public string ActorName { get; set; } = null!;
+
+    /// <summary>
+    /// The identifier of the actor.
+    /// </summary>
     public string ActorId { get; set; } = null!;
 }
 
 public sealed class SearchDialogTransmissionContentDto
 {
+    /// <summary>
+    /// The title of the content.
+    /// </summary>
     public ContentValueDto Title { get; set; } = null!;
+
+    /// <summary>
+    /// The summary of the content.
+    /// </summary>
     public ContentValueDto Summary { get; set; } = null!;
+
+    /// <summary>
+    /// Front-channel embedded content. Used to dynamically embed content in the frontend from an external URL.
+    /// </summary>
+    public ContentValueDto? ContentReference { get; set; }
 }
 
 public sealed class SearchDialogTransmissionAttachmentDto
 {
+    /// <summary>
+    /// The unique identifier for the attachment in UUIDv7 format.
+    /// </summary>
     public Guid Id { get; set; }
 
+    /// <summary>
+    /// The display name of the attachment that should be used in GUIs.
+    /// </summary>
     public List<LocalizationDto> DisplayName { get; set; } = [];
+
+    /// <summary>
+    /// The URLs associated with the attachment, each referring to a different representation of the attachment.
+    /// </summary>
     public List<SearchDialogTransmissionAttachmentUrlDto> Urls { get; set; } = [];
 }
 
 public sealed class SearchDialogTransmissionAttachmentUrlDto
 {
+    /// <summary>
+    /// The unique identifier for the attachment URL in UUIDv7 format.
+    /// </summary>
     public Guid Id { get; set; }
+
+    /// <summary>
+    /// The fully qualified URL of the attachment. Will be set to "urn:dialogporten:unauthorized" if the user is
+    /// not authorized to access the transmission.
+    /// </summary>
+    /// <example>
+    /// https://someendpoint.com/someattachment.pdf
+    /// urn:dialogporten:unauthorized
+    /// </example>
     public Uri Url { get; set; } = null!;
+
+    /// <summary>
+    /// The media type of the attachment.
+    /// </summary>
+    /// <example>
+    /// application/pdf
+    /// application/zip
+    /// </example>
     public string? MediaType { get; set; } = null!;
 
+    /// <summary>
+    /// The type of consumer the URL is intended for.
+    /// </summary>
     public AttachmentUrlConsumerType.Values ConsumerType { get; set; }
 }