updata

docs/spec.md

@@ -116,6 +116,73 @@ This specification serves as the single source of truth for:
 
 ---
 
+## Payload Format
+
+### Tuple Format for `smartsend()`
+
+The `smartsend()` function accepts data as an array of tuples with the format:
+
+```
+("data_name", data, "data_type")
+```
+
+| Position | Type | Description | Example |
+|----------|------|-------------|---------|
+| 1 | `string` | Data name - identifier for the payload | `"msg"`, `"login_image"`, `"user_data"` |
+| 2 | `any` | Actual data - content to be serialized | `"Hello"`, `{"key": "value"}`, `DataFrame(...)` |
+| 3 | `string` | Data type - must be in `payload_type` enum | `"text"`, `"dictionary"`, `"arrowtable"` |
+
+### Single Payload Example
+
+```julia
+# Julia
+smartsend("/chat/user/v1/message", [("msg", "Hello World", "text")])
+```
+
+```python
+# Python
+await smartsend("/chat/user/v1/message", [("msg", "Hello World", "text")])
+```
+
+```typescript
+// JavaScript
+await smartsend("/chat/user/v1/message", [["msg", "Hello World", "text"]]);
+```
+
+### Multiple Payloads Example
+
+```julia
+# Julia - Mixed text and binary data
+data = [
+    ("msg", "Hello", "text"),
+    ("img", binary_data, "image")
+]
+smartsend("/agent/v1/process", data)
+```
+
+```python
+# Python - Mixed types
+data = [
+    ("msg", "Hello", "text"),
+    ("img", binary_data, "image")
+]
+await smartsend("/agent/v1/process", data)
+```
+
+### Data Type Mapping
+
+| Platform | Input Type | Data Type String |
+|----------|------------|------------------|
+| All | `String` | `"text"` |
+| All | `Dict`/`Object` | `"dictionary"` |
+| Desktop | `DataFrame` | `"arrowtable"` or `"jsontable"` |
+| All | `Array` of objects | `"jsontable"` |
+| All | `Uint8Array`/`Buffer`/`bytes` | `"binary"` |
+| Desktop | `Arrow.Table` | `"arrowtable"` |
+| All | Image/Audio/Video binary | `"image"`, `"audio"`, `"video"` |
+
+---
+
 ## Enumerations
 
 ### `msg_purpose` Enum
@@ -649,7 +716,7 @@ flowchart TD
 | Dictionary round-trip | `("data", {"key": "value"}, "dictionary")` | `("data", {"key": "value"}, "dictionary")` | JSON object round-trip |
 | Arrow table round-trip | `("table", arrow_table_data, "arrowtable")` | `("table", arrow_table_data, "arrowtable")` | Arrow IPC round-trip |
 | JSON table round-trip | `("table", [{"a":1},{"b":2}], "jsontable")` | `("table", [{"a":1},{"b":2}], "jsontable")` | JSON array of objects |
-| Mixed payloads | `[("text", "Hello", "text"), ("img", bytes, "image")]` | `[("text", "Hello", "text"), ("img", bytes, "image")]` | Multiple payload types |
+| Mixed payloads | `[("msg", "Hello", "text"), ("imgname", bytes, "binary")]` | `[("msg", "Hello", "text"), ("imgname", bytes, "binary")]` | Multiple payload types |
 | Large payload | `("data", rand(10_000_000), "arrowtable")` | `("data", URL, "arrowtable")` with link transport | File server upload |
 
 **Platform-Specific Notes:**