Implement notifications service with shared messaging and email drivers (#36)

backend/notifications/interface/proto/v1/interface.proto

@@ -0,0 +1,73 @@
+syntax = "proto3";
+package sxchnge.notifications.v1;
+option go_package = "git.sendico.io/tech/sxchnge/notifications/interface/notifications/v1;notificationsv1";
+import "google/protobuf/timestamp.proto";
+
+// Internal service: authenticate callers over TLS. Send durably queues work.
+service NotificationsService {
+  rpc Send(SendRequest) returns (SendResponse);
+  rpc Get(GetRequest) returns (GetResponse);
+}
+message SendRequest {
+  string idempotency_key = 1; // Required; scoped to authenticated caller, retained seven days.
+  string user_id = 2; // Caller resolves and authorizes recipient ownership.
+  string template_id = 3;
+  string template_version = 4;
+  map<string, string> parameters = 5;
+  string locale = 6;
+  repeated Target targets = 7; // V1 accepts exactly one email target.
+  google.protobuf.Timestamp expires_at = 8; // Default/max 24h from acceptance.
+}
+message Target {
+  oneof destination {
+    EmailTarget email = 1;
+    SmsTarget sms = 2;
+    PushTarget push = 3;
+    TelegramTarget telegram = 4;
+  }
+}
+message EmailTarget { string address = 1; }
+message SmsTarget { string phone_number = 1; }
+message PushTarget { string endpoint_id = 1; }
+message TelegramTarget { string chat_id = 1; }
+message SendResponse { Notification notification = 1; }
+message GetRequest { string id = 1; }
+message GetResponse { Notification notification = 1; }
+message Notification {
+  string id = 1;
+  string user_id = 2;
+  string template_id = 3;
+  string template_version = 4;
+  repeated Delivery deliveries = 5;
+  google.protobuf.Timestamp created_at = 6;
+  google.protobuf.Timestamp updated_at = 7;
+  google.protobuf.Timestamp expires_at = 8;
+}
+message Delivery {
+  string id = 1;
+  Channel channel = 2;
+  DeliveryState state = 3;
+  uint32 attempt_count = 4;
+  Failure failure = 5;
+  google.protobuf.Timestamp next_attempt_at = 6;
+  google.protobuf.Timestamp updated_at = 7;
+}
+message Failure { string code = 1; string message = 2; }
+enum Channel {
+  CHANNEL_UNSPECIFIED = 0;
+  CHANNEL_EMAIL = 1;
+  CHANNEL_SMS = 2;
+  CHANNEL_PUSH = 3;
+  CHANNEL_TELEGRAM = 4;
+}
+enum DeliveryState {
+  DELIVERY_STATE_UNSPECIFIED = 0;
+  DELIVERY_STATE_QUEUED = 1;
+  DELIVERY_STATE_SENDING = 2;
+  DELIVERY_STATE_RETRY_WAIT = 3;
+  DELIVERY_STATE_ACCEPTED = 4;
+  DELIVERY_STATE_DELIVERED = 5; // Reserved for future verified receipts.
+  DELIVERY_STATE_FAILED = 6;
+  DELIVERY_STATE_EXPIRED = 7;
+  DELIVERY_STATE_UNKNOWN = 8; // May have sent; no automatic replay.
+}