The proto file

// FireFlo SMS gateway: gRPC API, version 1.
// Frozen contract. Field numbers are never reused or renumbered; additions only.
syntax = "proto3";

package fireflo.v1;

option java_multiple_files = true;
option java_outer_classname = "FireFloProto";
option go_package = "fireflo/v1;fireflov1";
option csharp_namespace = "FireFlo.V1";

import "google/protobuf/timestamp.proto";

// ---------------------------------------------------------------- Auth
// Call Login once per channel; send the token on every other call as
//   authorization: Bearer <session_token>
service AuthService {
  rpc Login(LoginRequest) returns (LoginResponse);
  rpc Logout(LogoutRequest) returns (LogoutResponse);
  // A platform session (from 0.15.10): for a platform that provisions accounts with
  // the gateway's management token and sends on their behalf. No password; the call
  // is signed with the management token instead (see PlatformLoginRequest). The
  // token returned is used exactly as a Login token.
  rpc PlatformLogin(PlatformLoginRequest) returns (LoginResponse);
}

message LoginRequest {
  string system_id = 1;   // the HTTP login (same as REST Basic username)
  string password  = 2;
}
message LoginResponse {
  string session_token = 1;
  google.protobuf.Timestamp expires_at = 2;   // absolute cap; idle expiry also applies
  int64  idle_timeout_seconds = 3;
}
message LogoutRequest {}
message LogoutResponse {}

// Signed, not passworded. The call carries three metadata entries:
//   x-fireflo-timestamp  Unix time in seconds, within 60 s of the gateway's clock
//   x-fireflo-nonce      1..128 characters, unique per call; a nonce is accepted once
//   x-fireflo-signature  hex HMAC-SHA256, keyed by the management token, of these
//                        five lines joined by "\n", with no trailing newline:
//                          POST
//                          /fireflo.v1.AuthService/PlatformLogin
//                          <the timestamp, as sent>
//                          <the nonce, as sent>
//                          <lowercase hex SHA-256 of this message's serialized bytes>
// The session acts for the accounts whose ref (the marker the platform provisioned
// them with) starts with this ref, and for no other.
message PlatformLoginRequest {
  optional string ref = 1;   // required: a prefix of the accounts' refs, ending in "/"
}

// ---------------------------------------------------------------- Send
service SendService {
  // One message. Mirrors POST /secure/send.
  rpc Send(SendRequest) returns (SendResponse);
  // Many messages on one stream. Results arrive in any order, one per request,
  // matched by correlation_id. A refusal is a result, not a stream error.
  rpc SendStream(stream SendStreamRequest) returns (stream SendStreamResult);
}

// Field for field the body of POST /secure/send. Unset optional fields take the
// same defaults as an absent JSON key.
message SendRequest {
  string to = 1;
  optional string from = 2;
  // exactly one of content / hex_content
  optional string content = 3;
  optional string hex_content = 4;
  optional int32  coding = 5;            // 0 GSM-7 default, 8 UCS-2, ... as REST
  optional int32  priority = 6;          // 0..3
  optional int32  validity_period = 7;   // minutes
  optional string sdt = 8;               // scheduled delivery time, REST format
  optional bool   dlr = 9;               // request receipts (to the feed unless dlr_url set)
  optional int32  dlr_level = 10;        // 1 progress, 2 final, 3 both
  map<string, TlvValue> custom_tlvs = 11; // key "0xTAG" or "0xTAG:Type", as REST
  optional string client_ref = 12;       // 1..64 printable chars; idempotency key
  optional string product = 13;
  optional string dlr_url = 14;          // if set, receipts go to this webhook and NOT the feed
  reserved 15, 16;                       // dlr_method, tags (REST/Jasmin compatibility; not carried)
  // Platform sessions only, and required on them: the account to send as. The
  // message runs under that account's enabled HTTP login, with its prices, limits
  // and receipt feed. Refused on a Login session.
  optional string account = 17;
}

message TlvValue {
  oneof value {
    string string_value = 1;
    int64  int_value    = 2;
    uint64 uint_value   = 3;   // up to 2^64-1 exactly, the same range REST takes as a JSON integer
  }
}

message SendResponse {
  string message_id = 1;
  bool   duplicate = 2;        // client_ref seen before: message_id is the original's, nothing charged
  optional string price = 3;   // decimal string, 4 places, whole message (REST "price")
  optional string currency = 4;
  optional int32  segments = 5;
  bool   unrated = 6;
}

message SendStreamRequest {
  string correlation_id = 1;   // client-chosen, 1..64 chars, echoed back
  SendRequest request = 2;
}

message SendStreamResult {
  string correlation_id = 1;
  int32  code = 2;             // google.rpc.Code value the unary Send would have returned (0 = OK)
  SendResponse response = 3;   // set when code == 0
  ErrorDetail error = 4;       // set when code != 0
}

// Packed into google.rpc.Status.details on every non-OK unary status,
// and inline in SendStreamResult.
message ErrorDetail {
  int32  http_status = 1;      // what POST /secure/send would have answered
  string code = 2;             // REST error code, e.g. RATE_LIMITED, OUTCOME_UNKNOWN, SHUTTING_DOWN
  string message = 3;          // REST error message, verbatim
  optional int32  retry_after_seconds = 4;
  optional string message_id = 5;   // OUTCOME_UNKNOWN only
  optional string field = 6;        // the offending request field for INVALID_ARGUMENT
}

// ---------------------------------------------------------------- Receipts
// One durable queue per HTTP login. Subscribe and Pull draw from the same queue.
// Delivery is at least once: a receipt is removed only by Ack. An unacked receipt
// is redelivered after its lease (default 120 s) or as soon as its stream closes.
// On a platform session the three calls read the receipts of every account the
// platform owns; account_id and system_id say whose each one is. An ack token is
// accepted only by the kind of session (login or platform) it was delivered to.
service ReceiptService {
  rpc Subscribe(SubscribeRequest) returns (stream Receipt);
  rpc Pull(PullRequest) returns (PullResponse);
  rpc Ack(AckRequest) returns (AckResponse);
}

message SubscribeRequest {
  optional int32 window = 1;   // max unacked receipts in flight on this stream; server caps
}
message PullRequest {
  int32 max = 1;               // 1..1000 (server cap)
  optional int32 wait_seconds = 2;   // long-poll up to 20 s when empty; 0 = return at once
}
message PullResponse {
  repeated Receipt receipts = 1;
}
message AckRequest {
  repeated string ack_tokens = 1;    // up to 1000
}
message AckResponse {
  int32 acked = 1;                   // removed now
  int32 already_gone = 2;            // unknown, already acked or expired: not an error
}

// The receipt webhook JSON (docs.fireflo.au/reference/api/dlr-webhook), one field per key, plus delivery fields.
message Receipt {
  string id = 1;                     // message_id from SendResponse
  string stat = 2;                   // DELIVRD, UNDELIV, EXPIRED, REJECTD, UNKNOWN, ACCEPTD, ENROUTE...
  int32  level = 3;                  // 1 progress, 2 final
  optional string sub_date = 4;
  optional string done_date = 5;
  optional string to = 6;
  optional string from = 7;
  optional string operator_msg_id = 8;
  optional string account_id = 9;
  optional string system_id = 10;
  optional int32  parts = 11;
  optional string vendor = 12;       // absent unless the operator shares it
  optional string err = 13;
  string ack_token = 14;
  int32  delivery_count = 15;        // 1 on first delivery; >1 means a redelivery
}