Add Send API to Waku API

standards/application/waku-api.md

@@ -69,7 +69,7 @@ An alternative would be to choose a programming language. However, such choice m
 ### Primitive types and general guidelines
 
 - No `default` means that the value is mandatory, meaning a `default` value implies an optional parameter.
-- Primitive types are `string`, `int`, `bool`, `enum` and `uint`
+- Primitive types are `string`, `int`, `bool`, `byte`, `enum` and `uint`
 - Complex pre-defined types are:
   - `object`: object and other nested types.
   - `array`: iterable object containing values of all the same type.
@@ -302,6 +302,109 @@ If the `mode` set is `core`, the initialised `WakuNode` SHOULD use:
 `edge` mode SHOULD be used if node functions in resource restricted environment,
 whereas `core` SHOULD be used if node has no strong hardware or bandwidth restrictions.
 
+## Send messages
+
+#### Type definitions
+
+```yaml
+types:
+  SendMessage:
+    type: object
+    fields:
+      contentTopic:
+        type: string
+        description: "Content-based filtering field as defined in [TOPICS](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md#content-topics)"
+      payload:
+        type: array<byte>
+        description: "The message data to be sent."
+      ephemeral:
+        type: bool
+        default: false
+        description: "Whether the message is ephemeral. Read at [ATTRIBUTES](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md#message-attributes)"
+
+  RequestId:
+    type: string
+    description: "A unique identifier for a request"
+```
+
+#### Function definitions
+
+```yaml
+functions:
+  send:
+    description: "Send a message through the network."
+    parameters:
+      - name: message
+        type: SendMessage
+        description: "The message to send"
+    returns:
+      type: result<RequestId, error>
+```
+
+#### Extended definitions
+
+When `message` is sent with `contentTopic` for the first time,
+the node SHOULD trigger a subscription based on `Subscribe to messages` section.
+
+The node uses [P2P-RELIABILITY](/standards/application/p2p-reliability.md) strategies to ensure message delivery.
+
+## Event source
+
+#### Type definitions
+
+```yaml
+types:
+  MessageSentEvent:
+    type: object
+    fields:
+      eventType:
+        type: string
+        default: "message:sent"
+        description: "Event type identifier"
+      requestId:
+        type: RequestId
+        description: "The request ID associated with the sent message"
+
+  MessageErrorEvent:
+    type: object
+    fields:
+      eventType:
+        type: string
+        default: "message:error"
+        description: "Event type identifier"
+      requestId:
+        type: RequestId
+        description: "The request ID associated with the failed message"
+      error:
+        type: string
+        description: "Error message describing what went wrong"
+
+  MessagePropagatedEvent:
+    type: object
+    fields:
+      eventType:
+        type: string
+        default: "message:propagated"
+        description: "Event type identifier"
+      requestId:
+        type: RequestId
+        description: "The request ID associated with the propagated message in the network"
+      messageHash:
+        type: string
+        description: "Hash of the message that got propagated within the network"
+
+  EventSource:
+    type: object
+    description: "Event source for message-related events"
+    fields:
+      onEvent:
+        type: function
+        description: "Callback for message:sent events"
+        parameters:
+          - name: event
+            type: MessageSentEvent | MessageErrorEvent | MessageAckEvent
+```
+
 ## The Validation API
 
 [WAKU2-RLN-RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/17/rln-relay.md) is currently the primary message validation mechanism in place.