notifier/api/grpc/notifier.proto

syntax = "proto3";

package notifier.v1;

option go_package = "github.com/igodwin/notifier/api/grpc/pb";

import "google/protobuf/timestamp.proto";

// NotifierService handles notification operations
service NotifierService {
  // SendNotification sends a single notification
  rpc SendNotification(SendNotificationRequest) returns (SendNotificationResponse);

  // SendBatchNotifications sends multiple notifications
  rpc SendBatchNotifications(SendBatchNotificationsRequest) returns (SendBatchNotificationsResponse);

  // GetNotification retrieves a notification by ID
  rpc GetNotification(GetNotificationRequest) returns (GetNotificationResponse);

  // ListNotifications retrieves notifications matching a filter
  rpc ListNotifications(ListNotificationsRequest) returns (ListNotificationsResponse);

  // CancelNotification cancels a pending notification
  rpc CancelNotification(CancelNotificationRequest) returns (CancelNotificationResponse);

  // RetryNotification retries a failed notification
  rpc RetryNotification(RetryNotificationRequest) returns (RetryNotificationResponse);

  // GetStats returns notification statistics
  rpc GetStats(GetStatsRequest) returns (GetStatsResponse);

  // GetNotifiers returns information about available notifiers
  rpc GetNotifiers(GetNotifiersRequest) returns (GetNotifiersResponse);

  // HealthCheck verifies the service is operational
  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
}

// NotificationType defines the channel for notification delivery
enum NotificationType {
  NOTIFICATION_TYPE_UNSPECIFIED = 0;
  NOTIFICATION_TYPE_EMAIL = 1;
  NOTIFICATION_TYPE_SLACK = 2;
  NOTIFICATION_TYPE_NTFY = 3;
  NOTIFICATION_TYPE_STDOUT = 4;
}

// Priority defines the urgency level
enum Priority {
  PRIORITY_UNSPECIFIED = 0;
  PRIORITY_LOW = 1;
  PRIORITY_NORMAL = 2;
  PRIORITY_HIGH = 3;
  PRIORITY_CRITICAL = 4;
}

// ContentType defines the format of the notification body
enum ContentType {
  CONTENT_TYPE_UNSPECIFIED = 0;
  CONTENT_TYPE_TEXT = 1;
  CONTENT_TYPE_HTML = 2;
}

// NotificationStatus represents the state of a notification
enum NotificationStatus {
  NOTIFICATION_STATUS_UNSPECIFIED = 0;
  NOTIFICATION_STATUS_PENDING = 1;
  NOTIFICATION_STATUS_QUEUED = 2;
  NOTIFICATION_STATUS_PROCESSING = 3;
  NOTIFICATION_STATUS_SENT = 4;
  NOTIFICATION_STATUS_FAILED = 5;
  NOTIFICATION_STATUS_RETRYING = 6;
}

// Notification represents a notification message
message Notification {
  string id = 1;
  NotificationType type = 2;
  string account = 3; // Optional account name for multi-account configs
  Priority priority = 4;
  NotificationStatus status = 5;
  string subject = 6;
  string body = 7;
  ContentType content_type = 18 [deprecated = true]; // Deprecated: use html_body instead. Format of the body (text or html).
  string html_body = 19; // Optional HTML body for email; if set, sends multipart/alternative with body as text/plain and html_body as text/html. Ignored for non-email types.
  repeated string recipients = 8;
  repeated string cc = 16; // Carbon copy recipients (email only)
  repeated string bcc = 17; // Blind carbon copy recipients (email only)
  map<string, string> metadata = 9;
  google.protobuf.Timestamp created_at = 10;
  google.protobuf.Timestamp scheduled_for = 11;
  google.protobuf.Timestamp sent_at = 12;
  int32 retry_count = 13;
  int32 max_retries = 14;
  string last_error = 15;
}

// NotificationResult represents the outcome of sending a notification
message NotificationResult {
  string notification_id = 1;
  bool success = 2;
  string message = 3;
  string error = 4;
  google.protobuf.Timestamp sent_at = 5;
  map<string, string> provider_response = 6;
}

// SendNotificationRequest sends a single notification
message SendNotificationRequest {
  NotificationType type = 1;
  string account = 2; // Optional account name for multi-account configs
  Priority priority = 3;
  string subject = 4;
  string body = 5;
  ContentType content_type = 12 [deprecated = true]; // Deprecated: use html_body instead. Format of the body (text or html) - auto-detected if not specified.
  repeated string recipients = 6;
  repeated string cc = 10; // Carbon copy recipients (email only)
  repeated string bcc = 11; // Blind carbon copy recipients (email only)
  map<string, string> metadata = 7;
  google.protobuf.Timestamp scheduled_for = 8;
  int32 max_retries = 9;
  string html_body = 13; // Optional HTML body for email; if set, sends multipart/alternative with body as text/plain and html_body as text/html. Ignored for non-email types.
}

// SendNotificationResponse returns the result of sending a notification
message SendNotificationResponse {
  NotificationResult result = 1;
}

// SendBatchNotificationsRequest sends multiple notifications
message SendBatchNotificationsRequest {
  repeated SendNotificationRequest notifications = 1;
}

// SendBatchNotificationsResponse returns the results of sending multiple notifications
message SendBatchNotificationsResponse {
  repeated NotificationResult results = 1;
}

// GetNotificationRequest retrieves a notification by ID
message GetNotificationRequest {
  string id = 1;
}

// GetNotificationResponse returns a notification
message GetNotificationResponse {
  Notification notification = 1;
}

// NotificationFilter is used for querying notifications
message NotificationFilter {
  repeated string ids = 1;
  repeated NotificationType types = 2;
  repeated NotificationStatus statuses = 3;
  repeated string recipients = 4;
  google.protobuf.Timestamp created_after = 5;
  google.protobuf.Timestamp created_before = 6;
  int32 limit = 7;
  int32 offset = 8;
}

// ListNotificationsRequest retrieves notifications matching a filter
message ListNotificationsRequest {
  NotificationFilter filter = 1;
}

// ListNotificationsResponse returns a list of notifications
message ListNotificationsResponse {
  repeated Notification notifications = 1;
  int64 total = 2;
}

// CancelNotificationRequest cancels a pending notification
message CancelNotificationRequest {
  string id = 1;
}

// CancelNotificationResponse returns the result of canceling a notification
message CancelNotificationResponse {
  bool success = 1;
  string message = 2;
}

// RetryNotificationRequest retries a failed notification
message RetryNotificationRequest {
  string id = 1;
}

// RetryNotificationResponse returns the result of retrying a notification
message RetryNotificationResponse {
  NotificationResult result = 1;
}

// GetStatsRequest requests notification statistics
message GetStatsRequest {}

// GetStatsResponse returns notification statistics
message GetStatsResponse {
  int64 total_sent = 1;
  int64 total_failed = 2;
  int64 total_pending = 3;
  int64 total_queued = 4;
  map<string, int64> by_type = 5;
  map<string, int64> by_status = 6;
  double average_latency_ms = 7;
}

// GetNotifiersRequest requests available notifiers
message GetNotifiersRequest {}

// NotifierInfo contains information about a configured notifier type
message NotifierInfo {
  NotificationType type = 1;
  repeated string accounts = 2;
  string default_account = 3;
}

// GetNotifiersResponse returns available notifiers
message GetNotifiersResponse {
  repeated NotifierInfo notifiers = 1;
}

// HealthCheckRequest requests health status
message HealthCheckRequest {}

// HealthCheckResponse returns health status
message HealthCheckResponse {
  bool healthy = 1;
  string status = 2;
  map<string, string> components = 3;
}