up

src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/Contracts/IncidentContracts.cs

@@ -0,0 +1,121 @@
+namespace StellaOps.Notifier.WebService.Contracts;
+
+/// <summary>
+/// Incident list query parameters.
+/// </summary>
+public sealed record IncidentListQuery
+{
+    /// <summary>
+    /// Filter by status (open, acknowledged, resolved).
+    /// </summary>
+    public string? Status { get; init; }
+
+    /// <summary>
+    /// Filter by event kind prefix.
+    /// </summary>
+    public string? EventKindPrefix { get; init; }
+
+    /// <summary>
+    /// Filter incidents after this timestamp.
+    /// </summary>
+    public DateTimeOffset? Since { get; init; }
+
+    /// <summary>
+    /// Filter incidents before this timestamp.
+    /// </summary>
+    public DateTimeOffset? Until { get; init; }
+
+    /// <summary>
+    /// Maximum number of results.
+    /// </summary>
+    public int? Limit { get; init; }
+
+    /// <summary>
+    /// Cursor for pagination.
+    /// </summary>
+    public string? Cursor { get; init; }
+}
+
+/// <summary>
+/// Incident response DTO.
+/// </summary>
+public sealed record IncidentResponse
+{
+    public required string IncidentId { get; init; }
+    public required string TenantId { get; init; }
+    public required string EventKind { get; init; }
+    public required string Status { get; init; }
+    public required string Severity { get; init; }
+    public required string Title { get; init; }
+    public string? Description { get; init; }
+    public required int EventCount { get; init; }
+    public required DateTimeOffset FirstOccurrence { get; init; }
+    public required DateTimeOffset LastOccurrence { get; init; }
+    public string? AcknowledgedBy { get; init; }
+    public DateTimeOffset? AcknowledgedAt { get; init; }
+    public string? ResolvedBy { get; init; }
+    public DateTimeOffset? ResolvedAt { get; init; }
+    public List<string>? Labels { get; init; }
+    public Dictionary<string, string>? Metadata { get; init; }
+}
+
+/// <summary>
+/// Incident list response with pagination.
+/// </summary>
+public sealed record IncidentListResponse
+{
+    public required List<IncidentResponse> Incidents { get; init; }
+    public required int TotalCount { get; init; }
+    public string? NextCursor { get; init; }
+}
+
+/// <summary>
+/// Request to acknowledge an incident.
+/// </summary>
+public sealed record IncidentAckRequest
+{
+    /// <summary>
+    /// Actor performing the acknowledgement.
+    /// </summary>
+    public string? Actor { get; init; }
+
+    /// <summary>
+    /// Optional comment.
+    /// </summary>
+    public string? Comment { get; init; }
+}
+
+/// <summary>
+/// Request to resolve an incident.
+/// </summary>
+public sealed record IncidentResolveRequest
+{
+    /// <summary>
+    /// Actor resolving the incident.
+    /// </summary>
+    public string? Actor { get; init; }
+
+    /// <summary>
+    /// Resolution reason.
+    /// </summary>
+    public string? Reason { get; init; }
+
+    /// <summary>
+    /// Optional comment.
+    /// </summary>
+    public string? Comment { get; init; }
+}
+
+/// <summary>
+/// Delivery history item for an incident.
+/// </summary>
+public sealed record DeliveryHistoryItem
+{
+    public required string DeliveryId { get; init; }
+    public required string ChannelType { get; init; }
+    public required string ChannelName { get; init; }
+    public required string Status { get; init; }
+    public required DateTimeOffset Timestamp { get; init; }
+    public string? ErrorMessage { get; init; }
+    public int Attempts { get; init; }
+}

src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/Contracts/PackApprovalAckRequest.cs

@@ -1,9 +1,35 @@
 using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
 
 namespace StellaOps.Notifier.WebService.Contracts;
 
+/// <summary>
+/// Request payload for acknowledging a pack approval decision.
+/// </summary>
 public sealed class PackApprovalAckRequest
 {
+    /// <summary>
+    /// Acknowledgement token from the notification.
+    /// </summary>
     [Required]
+    [JsonPropertyName("ackToken")]
     public string AckToken { get; init; } = string.Empty;
+
+    /// <summary>
+    /// Approval decision: "approved" or "rejected".
+    /// </summary>
+    [JsonPropertyName("decision")]
+    public string? Decision { get; init; }
+
+    /// <summary>
+    /// Optional comment for audit trail.
+    /// </summary>
+    [JsonPropertyName("comment")]
+    public string? Comment { get; init; }
+
+    /// <summary>
+    /// Identity acknowledging the approval.
+    /// </summary>
+    [JsonPropertyName("actor")]
+    public string? Actor { get; init; }
 }

src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/Contracts/PackApprovalRequest.cs

@@ -2,44 +2,87 @@ using System.Text.Json.Serialization;
 
 namespace StellaOps.Notifier.WebService.Contracts;
 
+/// <summary>
+/// Request payload for pack approval events from Task Runner.
+/// See: docs/notifications/pack-approvals-contract.md
+/// </summary>
 public sealed class PackApprovalRequest
 {
+    /// <summary>
+    /// Unique event identifier for deduplication.
+    /// </summary>
     [JsonPropertyName("eventId")]
     public Guid EventId { get; init; }
 
+    /// <summary>
+    /// Event timestamp in UTC (ISO 8601).
+    /// </summary>
     [JsonPropertyName("issuedAt")]
     public DateTimeOffset IssuedAt { get; init; }
 
+    /// <summary>
+    /// Event type: pack.approval.requested, pack.approval.updated, pack.policy.hold, pack.policy.released.
+    /// </summary>
     [JsonPropertyName("kind")]
     public string Kind { get; init; } = string.Empty;
 
+    /// <summary>
+    /// Package identifier in PURL format.
+    /// </summary>
     [JsonPropertyName("packId")]
     public string PackId { get; init; } = string.Empty;
 
+    /// <summary>
+    /// Policy metadata (id and version).
+    /// </summary>
     [JsonPropertyName("policy")]
     public PackApprovalPolicy? Policy { get; init; }
 
+    /// <summary>
+    /// Current approval state: pending, approved, rejected, hold, expired.
+    /// </summary>
     [JsonPropertyName("decision")]
     public string Decision { get; init; } = string.Empty;
 
+    /// <summary>
+    /// Identity that triggered the event.
+    /// </summary>
     [JsonPropertyName("actor")]
     public string Actor { get; init; } = string.Empty;
 
+    /// <summary>
+    /// Opaque token for Task Runner resume flow. Echoed in X-Resume-After header.
+    /// </summary>
     [JsonPropertyName("resumeToken")]
     public string? ResumeToken { get; init; }
 
+    /// <summary>
+    /// Human-readable summary for notifications.
+    /// </summary>
     [JsonPropertyName("summary")]
     public string? Summary { get; init; }
 
+    /// <summary>
+    /// Custom key-value metadata labels.
+    /// </summary>
     [JsonPropertyName("labels")]
     public Dictionary<string, string>? Labels { get; init; }
 }
 
+/// <summary>
+/// Policy metadata associated with a pack approval.
+/// </summary>
 public sealed class PackApprovalPolicy
 {
+    /// <summary>
+    /// Policy identifier.
+    /// </summary>
     [JsonPropertyName("id")]
     public string? Id { get; init; }
 
+    /// <summary>
+    /// Policy version.
+    /// </summary>
     [JsonPropertyName("version")]
     public string? Version { get; init; }
 }

src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/Contracts/RuleContracts.cs

@@ -0,0 +1,114 @@
+using System.Text.Json.Serialization;
+
+namespace StellaOps.Notifier.WebService.Contracts;
+
+/// <summary>
+/// Request to create or update a notification rule.
+/// </summary>
+public sealed record RuleCreateRequest
+{
+    public required string RuleId { get; init; }
+    public required string Name { get; init; }
+    public string? Description { get; init; }
+    public bool Enabled { get; init; } = true;
+    public required RuleMatchRequest Match { get; init; }
+    public required List<RuleActionRequest> Actions { get; init; }
+    public Dictionary<string, string>? Labels { get; init; }
+    public Dictionary<string, string>? Metadata { get; init; }
+}
+
+/// <summary>
+/// Request to update an existing rule.
+/// </summary>
+public sealed record RuleUpdateRequest
+{
+    public string? Name { get; init; }
+    public string? Description { get; init; }
+    public bool? Enabled { get; init; }
+    public RuleMatchRequest? Match { get; init; }
+    public List<RuleActionRequest>? Actions { get; init; }
+    public Dictionary<string, string>? Labels { get; init; }
+    public Dictionary<string, string>? Metadata { get; init; }
+}
+
+/// <summary>
+/// Rule match criteria.
+/// </summary>
+public sealed record RuleMatchRequest
+{
+    public List<string>? EventKinds { get; init; }
+    public List<string>? Namespaces { get; init; }
+    public List<string>? Repositories { get; init; }
+    public List<string>? Digests { get; init; }
+    public List<string>? Labels { get; init; }
+    public List<string>? ComponentPurls { get; init; }
+    public string? MinSeverity { get; init; }
+    public List<string>? Verdicts { get; init; }
+    public bool? KevOnly { get; init; }
+}
+
+/// <summary>
+/// Rule action configuration.
+/// </summary>
+public sealed record RuleActionRequest
+{
+    public required string ActionId { get; init; }
+    public required string Channel { get; init; }
+    public string? Template { get; init; }
+    public string? Digest { get; init; }
+    public string? Throttle { get; init; } // ISO 8601 duration
+    public string? Locale { get; init; }
+    public bool Enabled { get; init; } = true;
+    public Dictionary<string, string>? Metadata { get; init; }
+}
+
+/// <summary>
+/// Rule response DTO.
+/// </summary>
+public sealed record RuleResponse
+{
+    public required string RuleId { get; init; }
+    public required string TenantId { get; init; }
+    public required string Name { get; init; }
+    public string? Description { get; init; }
+    public required bool Enabled { get; init; }
+    public required RuleMatchResponse Match { get; init; }
+    public required List<RuleActionResponse> Actions { get; init; }
+    public Dictionary<string, string>? Labels { get; init; }
+    public Dictionary<string, string>? Metadata { get; init; }
+    public string? CreatedBy { get; init; }
+    public DateTimeOffset CreatedAt { get; init; }
+    public string? UpdatedBy { get; init; }
+    public DateTimeOffset UpdatedAt { get; init; }
+}
+
+/// <summary>
+/// Rule match response.
+/// </summary>
+public sealed record RuleMatchResponse
+{
+    public List<string> EventKinds { get; init; } = [];
+    public List<string> Namespaces { get; init; } = [];
+    public List<string> Repositories { get; init; } = [];
+    public List<string> Digests { get; init; } = [];
+    public List<string> Labels { get; init; } = [];
+    public List<string> ComponentPurls { get; init; } = [];
+    public string? MinSeverity { get; init; }
+    public List<string> Verdicts { get; init; } = [];
+    public bool KevOnly { get; init; }
+}
+
+/// <summary>
+/// Rule action response.
+/// </summary>
+public sealed record RuleActionResponse
+{
+    public required string ActionId { get; init; }
+    public required string Channel { get; init; }
+    public string? Template { get; init; }
+    public string? Digest { get; init; }
+    public string? Throttle { get; init; }
+    public string? Locale { get; init; }
+    public required bool Enabled { get; init; }
+    public Dictionary<string, string>? Metadata { get; init; }
+}

src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/Contracts/TemplateContracts.cs

@@ -0,0 +1,118 @@
+using System.Text.Json.Nodes;
+
+namespace StellaOps.Notifier.WebService.Contracts;
+
+/// <summary>
+/// Request to preview a template rendering.
+/// </summary>
+public sealed record TemplatePreviewRequest
+{
+    /// <summary>
+    /// Template ID to preview (mutually exclusive with TemplateBody).
+    /// </summary>
+    public string? TemplateId { get; init; }
+
+    /// <summary>
+    /// Raw template body to preview (mutually exclusive with TemplateId).
+    /// </summary>
+    public string? TemplateBody { get; init; }
+
+    /// <summary>
+    /// Sample event payload for rendering.
+    /// </summary>
+    public JsonObject? SamplePayload { get; init; }
+
+    /// <summary>
+    /// Event kind for context.
+    /// </summary>
+    public string? EventKind { get; init; }
+
+    /// <summary>
+    /// Sample attributes.
+    /// </summary>
+    public Dictionary<string, string>? SampleAttributes { get; init; }
+
+    /// <summary>
+    /// Output format override.
+    /// </summary>
+    public string? OutputFormat { get; init; }
+}
+
+/// <summary>
+/// Response from template preview.
+/// </summary>
+public sealed record TemplatePreviewResponse
+{
+    /// <summary>
+    /// Rendered body content.
+    /// </summary>
+    public required string RenderedBody { get; init; }
+
+    /// <summary>
+    /// Rendered subject (if applicable).
+    /// </summary>
+    public string? RenderedSubject { get; init; }
+
+    /// <summary>
+    /// Content hash for deduplication.
+    /// </summary>
+    public required string BodyHash { get; init; }
+
+    /// <summary>
+    /// Output format used.
+    /// </summary>
+    public required string Format { get; init; }
+
+    /// <summary>
+    /// Validation warnings (if any).
+    /// </summary>
+    public List<string>? Warnings { get; init; }
+}
+
+/// <summary>
+/// Request to create or update a template.
+/// </summary>
+public sealed record TemplateCreateRequest
+{
+    public required string TemplateId { get; init; }
+    public required string Key { get; init; }
+    public required string ChannelType { get; init; }
+    public required string Locale { get; init; }
+    public required string Body { get; init; }
+    public string? RenderMode { get; init; }
+    public string? Format { get; init; }
+    public string? Description { get; init; }
+    public Dictionary<string, string>? Metadata { get; init; }
+}
+
+/// <summary>
+/// Template response DTO.
+/// </summary>
+public sealed record TemplateResponse
+{
+    public required string TemplateId { get; init; }
+    public required string TenantId { get; init; }
+    public required string Key { get; init; }
+    public required string ChannelType { get; init; }
+    public required string Locale { get; init; }
+    public required string Body { get; init; }
+    public required string RenderMode { get; init; }
+    public required string Format { get; init; }
+    public string? Description { get; init; }
+    public Dictionary<string, string>? Metadata { get; init; }
+    public string? CreatedBy { get; init; }
+    public DateTimeOffset CreatedAt { get; init; }
+    public string? UpdatedBy { get; init; }
+    public DateTimeOffset UpdatedAt { get; init; }
+}
+
+/// <summary>
+/// Template list query parameters.
+/// </summary>
+public sealed record TemplateListQuery
+{
+    public string? KeyPrefix { get; init; }
+    public string? ChannelType { get; init; }
+    public string? Locale { get; init; }
+    public int? Limit { get; init; }
+}