ContactWise.Messaging.Contracts 0.1.1

ContactWise.Messaging.Contracts

Event contracts shared by the services of the ContactWise messaging platform. The types are plain data classes with no dependencies; their JSON shape is the wire contract between producers and consumers.

Installation

dotnet add package ContactWise.Messaging.Contracts

The package targets .NET 10 only, from version 0.1.0 onwards. Services still on .NET 8 stay on 0.0.5, the last version that targets net8.0, until they move to .NET 10.

What is in the package

... stands for ContactWise.Messaging.Contracts. Folders in the repository match the namespaces.

Usage

Producing an event:

using System.Text.Json;
using ContactWise.Messaging.Contracts.V1.Constants;
using ContactWise.Messaging.Contracts.V1.Enums;
using ContactWise.Messaging.Contracts.V1.Envelope;
using ContactWise.Messaging.Contracts.V1.Events;

var envelope = CloudEvent.Create(
    EventTypes.SmsRequestReceived,
    new Uri("urn:contactwise:my-service"),
    new SmsRequestReceivedEvent
    {
        Id = "request-id",
        TenantId = "tenant-id",
        From = "SENDER",
        To = "919999999999",
        Body = "Hello",
        MessageType = MessageType.Text
    });

string json = JsonSerializer.Serialize(envelope);

Create generates the envelope Id and sets Timestamp to the current UTC time. If you build the envelope with an object initializer instead, set Id, Source and Timestamp yourself: Id and Source default to empty and consumers rely on the pair to de-duplicate events, and Timestamp defaults to null.

Consuming an event:

// When the payload type is known, read the typed envelope. Its JSON shape is identical to CloudEvent.
var typed = JsonSerializer.Deserialize<CloudEvent<SmsRequestReceivedEvent>>(json)!;
SmsRequestReceivedEvent request = typed.Data!;

// When the payload type depends on Type, read the untyped envelope first. Data is declared as object,
// so System.Text.Json materialises it as a JsonElement.
var envelope = JsonSerializer.Deserialize<CloudEvent>(json)!;
var payload = ((JsonElement)envelope.Data!).Deserialize<SmsRequestReceivedEvent>()!;

Topics and event types

Topics is where a message is produced to and consumed from; EventTypes is the type attribute of the envelope inside the message. They are different strings, and one topic can carry more than one type, so consumers route on the type after reading.

An empty "Consumed by" means no consumer was found in the repositories checked when this table was written.

SMPP PDU audit event

sms_smpp_server publishes every SMPP PDU it receives or sends, one envelope per PDU. sms_smpp_connector will emit the same record on its own topic.

Producing:

var record = new SmppPduAuditEvent
{
    Timestamp = DateTimeOffset.UtcNow,
    Direction = SmppPduDirection.In,
    RemoteEndpoint = "203.0.113.9:51234",
    Command = "enquire_link",
    CommandId = "0x00000015",
    CommandStatus = "ESME_ROK",
    CommandStatusCode = 0,
    SequenceNumber = 9,
    Pdu = new Dictionary<string, object?>()
};

CloudEvent<SmppPduAuditEvent> envelope = record.ToCloudEvent(new Uri(EventSources.SmppServer), Guid.NewGuid().ToString(), traceParent);

The record (data):

• Nulls are written ("messageId": null), not omitted. Members that are not nullable are required: reading JSON that lacks one fails.
• direction is always "in" or "out", whatever enum converter your options register; reading ignores case.
• pdu keys are the SMPP 3.4 field names in snake_case and are written verbatim at every level, whatever DictionaryKeyPolicy your options set. Binary values are upper-case hex, cut at 1024 octets (short_message_truncated is true when the body was cut; sm_length keeps the real length). optional_parameters maps the TLV tag (0x + 4 hex digits) to the value in hex. When you read a record, every pdu value is a JsonElement.
• The bind password is never in a record. Producers write SmppPduFields.Redacted ([redacted]) in its place, or null when the bind carried none.
• A record with command generic_nack, direction in, sequenceNumber 0 and status ESME_RINVCMDID means "the peer sent a PDU that could not be decoded", not "the peer sent a generic_nack".

Serialization

The contracts are written for System.Text.Json.

• Every property carries an explicit [JsonPropertyName], so a naming policy on your JsonSerializerOptions does not change property names.
• Enum properties are always numbers on the wire. Each one carries a property-level JsonNumberEnumConverter, so a JsonStringEnumConverter registered on your options does not change them. A string such as "Unicode" is rejected when reading.
• Prefer not to produce with JsonIgnoreCondition.WhenWritingDefault or WhenWritingNull. A consumer falls back to the property's initial value for anything you omit, so an omitted null can come back as an empty string or dictionary.
• The envelope uses timestamp and content-type as attribute names rather than the CloudEvents time and datacontenttype. Existing consumers depend on these names.
• DeliveryStatusReceivedEvent mirrors the current vendor's delivery report field names verbatim (txid, deliverydt, corelationid, dltcontentid). Its formats are the vendor's and are not specified here; the shape will be replaced when delivery reports move to SMPP.
• to is the receiver and from is the sender. The contracts do not validate them; validation rules are applied by the Submission API.

Compatibility

• Contracts live in versioned namespaces (V1). Changes within a version are additive: new optional properties and new enum values appended at the end.
• JSON property names and enum numeric values are never renamed, reused or removed within a version. A breaking change ships as a new namespace (V2) alongside the old one.
• One exception was made before the first .NET 10 release: 0.1.0 renumbered MessageType (then called MessageTypeEnum) to Auto = 0, Text = 1, Unicode = 2 (up to 0.0.5 it was Text = 0, Unicode = 1, Auto = 2). Producers and consumers of messageType must move to 0.1.0 together, and stored values written with the old numbers need migrating or reinterpreting.
• Consumers should ignore properties they do not know and tolerate enum values they do not know.
• Every contract change is released as a new package version.

Upgrading from 0.0.5

0.1.0 renamed several C# types and properties and moved some types to new namespaces. JSON property names did not change, so none of this affects the wire.

The changes that do affect the wire or behaviour are listed in the package release notes; the MessageType renumbering is the one that needs producers and consumers to upgrade together.

Versioning

Package versions follow major.minor.patch:

While the version is 0.x, read the release notes before taking a new minor version. A breaking change to the JSON shape of an existing event never ships under the same namespace at any version; it becomes a new V2 type.

License

This project is licensed under the MIT License.