@myronsi/messenger-api 2.1.0-alpha.14 → 2.1.0-alpha.15

package/dist/ws-events.schema.json

@@ -202,6 +202,13 @@
         "invalid_client_version",
         "blocked_by_user",
         "approval_required",
+        "calls_unavailable",
+        "calls_not_allowed",
+        "call_identity_required",
+        "call_full",
+        "call_ended",
+        "already_in_call",
+        "stale_epoch",
         "internal_error"
       ]
     },
@@ -887,6 +894,7 @@
         "direct_messages",
         "group_invites",
         "search_visibility",
+        "calls_enabled",
         "exceptions"
       ],
       "properties": {
@@ -911,6 +919,10 @@
         "search_visibility": {
           "$ref": "#/$defs/SearchVisibility"
         },
+        "calls_enabled": {
+          "type": "boolean",
+          "description": "Whether others may ring this user. Calls are only possible from an existing direct chat or a shared group."
+        },
         "exceptions": {
           "$ref": "#/$defs/PrivacyExceptions"
         }
@@ -940,6 +952,9 @@
         },
         "search_visibility": {
           "$ref": "#/$defs/SearchVisibility"
+        },
+        "calls_enabled": {
+          "type": "boolean"
         }
       }
     },
@@ -1546,12 +1561,13 @@
         "member_added",
         "member_joined",
         "member_removed",
-        "member_left"
+        "member_left",
+        "call"
       ]
     },
     "SystemEvent": {
       "type": "object",
-      "description": "What a `system` message records; set on system messages only, whose `content` is then `null`. The names\nare the display names at the time of the event. `target` fields are set for `member_added` and\n`member_removed`.\n",
+      "description": "What a `system` message records; set on system messages only, whose `content` is then `null`. The names\nare the display names at the time of the event. `target` fields are set for `member_added` and\n`member_removed`. `call` is set for `call` messages: one per call, posted when the call ends, `actor` is the\ninitiator.\n",
       "required": [
         "kind",
         "actor_id",
@@ -1579,6 +1595,9 @@
         },
         "target_name": {
           "type": "string"
+        },
+        "call": {
+          "$ref": "#/$defs/CallSummary"
         }
       }
     },
@@ -2753,6 +2772,453 @@
         }
       }
     },
+    "CallConfig": {
+      "type": "object",
+      "required": [
+        "enabled",
+        "max_participants",
+        "ring_timeout_seconds"
+      ],
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "max_participants": {
+          "type": "integer",
+          "minimum": 2,
+          "description": "Most sessions joined to one call at the same time."
+        },
+        "ring_timeout_seconds": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "How long an invitation rings before it counts as missed."
+        }
+      }
+    },
+    "CallIdentityRequest": {
+      "type": "object",
+      "required": [
+        "public_key"
+      ],
+      "properties": {
+        "public_key": {
+          "$ref": "#/$defs/CallIdentityKey"
+        }
+      }
+    },
+    "CallIdentityKey": {
+      "type": "string",
+      "description": "P-256 public key as an uncompressed point (65 bytes, first byte `0x04`), base64url without padding.\n",
+      "minLength": 87,
+      "maxLength": 87,
+      "pattern": "^[A-Za-z0-9_-]+$"
+    },
+    "CallState": {
+      "type": "string",
+      "description": "`ringing` until someone answers, `active` while people are in it, `ended` afterwards.",
+      "enum": [
+        "ringing",
+        "active",
+        "ended"
+      ]
+    },
+    "CallEndReason": {
+      "type": "string",
+      "description": "Why the call ended: `completed` (people talked), `missed` (nobody answered in time), `declined` (the peer of a\ndirect call declined), `cancelled` (the caller hung up before an answer), `failed` (the media service lost\nthe call).\n",
+      "enum": [
+        "completed",
+        "missed",
+        "declined",
+        "cancelled",
+        "failed"
+      ]
+    },
+    "CallParticipantState": {
+      "type": "string",
+      "description": "`left` and `declined` can become `joined` again in a group call.",
+      "enum": [
+        "ringing",
+        "joined",
+        "declined",
+        "missed",
+        "left"
+      ]
+    },
+    "CallParticipant": {
+      "type": "object",
+      "required": [
+        "user_id",
+        "state",
+        "session_id",
+        "identity_key",
+        "joined_at"
+      ],
+      "properties": {
+        "user_id": {
+          "$ref": "#/$defs/Id"
+        },
+        "state": {
+          "$ref": "#/$defs/CallParticipantState"
+        },
+        "session_id": {
+          "description": "The session that joined; `null` unless `state` is `joined`.",
+          "oneOf": [
+            {
+              "type": "string",
+              "format": "uuid"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "identity_key": {
+          "description": "Call identity of the joined session; `null` unless `state` is `joined`.",
+          "oneOf": [
+            {
+              "$ref": "#/$defs/CallIdentityKey"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "joined_at": {
+          "description": "When the participant last joined; `null` if never.",
+          "oneOf": [
+            {
+              "$ref": "#/$defs/Timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "Call": {
+      "type": "object",
+      "required": [
+        "id",
+        "chat_id",
+        "kind",
+        "state",
+        "end_reason",
+        "initiator_id",
+        "created_at",
+        "started_at",
+        "ended_at",
+        "ring_expires_at",
+        "epoch",
+        "version",
+        "max_participants",
+        "participants"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/Id"
+        },
+        "chat_id": {
+          "$ref": "#/$defs/Id"
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "direct",
+            "group"
+          ]
+        },
+        "state": {
+          "$ref": "#/$defs/CallState"
+        },
+        "end_reason": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/CallEndReason"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "initiator_id": {
+          "$ref": "#/$defs/Id"
+        },
+        "created_at": {
+          "$ref": "#/$defs/Timestamp"
+        },
+        "started_at": {
+          "description": "First answer; `null` while nobody answered.",
+          "oneOf": [
+            {
+              "$ref": "#/$defs/Timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "ended_at": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/Timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "ring_expires_at": {
+          "description": "When ringing invitations of this call turn into `missed`.",
+          "$ref": "#/$defs/Timestamp"
+        },
+        "epoch": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Key epoch; increases whenever the set of joined sessions or their identity keys change."
+        },
+        "version": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Increases with every change of the call; ignore events with a lower version than one already seen."
+        },
+        "max_participants": {
+          "type": "integer",
+          "minimum": 2
+        },
+        "participants": {
+          "type": "array",
+          "description": "Everyone invited or joined, the initiator first.",
+          "items": {
+            "$ref": "#/$defs/CallParticipant"
+          }
+        }
+      }
+    },
+    "CallList": {
+      "type": "object",
+      "required": [
+        "items"
+      ],
+      "properties": {
+        "items": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Call"
+          }
+        }
+      }
+    },
+    "StartCallRequest": {
+      "type": "object",
+      "required": [
+        "client_request_id"
+      ],
+      "properties": {
+        "client_request_id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Idempotency key chosen by the client."
+        }
+      }
+    },
+    "JoinCallRequest": {
+      "type": "object",
+      "properties": {
+        "takeover": {
+          "type": "boolean",
+          "default": false,
+          "description": "Move the user's participation from another session to this one."
+        }
+      }
+    },
+    "CallGrant": {
+      "type": "object",
+      "required": [
+        "url",
+        "token",
+        "identity",
+        "expires_at"
+      ],
+      "properties": {
+        "url": {
+          "type": "string",
+          "description": "WebSocket URL of the media server (`wss://`)."
+        },
+        "token": {
+          "type": "string",
+          "description": "Media access token for this call and session only; microphone audio only."
+        },
+        "identity": {
+          "type": "string",
+          "description": "The participant identity inside the media room (`<user_id>:<session_id>`)."
+        },
+        "expires_at": {
+          "$ref": "#/$defs/Timestamp"
+        }
+      }
+    },
+    "CallJoin": {
+      "type": "object",
+      "required": [
+        "call",
+        "grant"
+      ],
+      "properties": {
+        "call": {
+          "$ref": "#/$defs/Call"
+        },
+        "grant": {
+          "$ref": "#/$defs/CallGrant"
+        }
+      }
+    },
+    "CallKeyEnvelope": {
+      "type": "object",
+      "description": "An HPKE Auth-mode envelope carrying one sender key (see `docs/calls-e2ee.md`).",
+      "required": [
+        "epoch",
+        "sender_user_id",
+        "sender_session_id",
+        "recipient_session_id",
+        "enc",
+        "ciphertext"
+      ],
+      "properties": {
+        "epoch": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "sender_user_id": {
+          "$ref": "#/$defs/Id"
+        },
+        "sender_session_id": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "recipient_session_id": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "enc": {
+          "type": "string",
+          "description": "HPKE encapsulated key, base64url without padding.",
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9_-]+$"
+        },
+        "ciphertext": {
+          "type": "string",
+          "description": "Sealed sender key, base64url without padding.",
+          "maxLength": 256,
+          "pattern": "^[A-Za-z0-9_-]+$"
+        }
+      }
+    },
+    "CallKeyEnvelopeList": {
+      "type": "object",
+      "required": [
+        "call_id",
+        "epoch",
+        "items"
+      ],
+      "properties": {
+        "call_id": {
+          "$ref": "#/$defs/Id"
+        },
+        "epoch": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "items": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/CallKeyEnvelope"
+          }
+        }
+      }
+    },
+    "SendCallKeysRequest": {
+      "type": "object",
+      "required": [
+        "epoch",
+        "envelopes"
+      ],
+      "properties": {
+        "epoch": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "envelopes": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "items": {
+            "$ref": "#/$defs/OutgoingCallKeyEnvelope"
+          }
+        }
+      }
+    },
+    "OutgoingCallKeyEnvelope": {
+      "type": "object",
+      "required": [
+        "recipient_session_id",
+        "enc",
+        "ciphertext"
+      ],
+      "properties": {
+        "recipient_session_id": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "enc": {
+          "type": "string",
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9_-]+$"
+        },
+        "ciphertext": {
+          "type": "string",
+          "maxLength": 256,
+          "pattern": "^[A-Za-z0-9_-]+$"
+        }
+      }
+    },
+    "CallSummary": {
+      "type": "object",
+      "description": "The call a `call` system message records.",
+      "required": [
+        "call_id",
+        "kind",
+        "outcome",
+        "duration_seconds"
+      ],
+      "properties": {
+        "call_id": {
+          "$ref": "#/$defs/Id"
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "direct",
+            "group"
+          ]
+        },
+        "outcome": {
+          "$ref": "#/$defs/CallEndReason"
+        },
+        "duration_seconds": {
+          "description": "From the first answer to the end; `null` if nobody answered.",
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
     "ClientDeleteEvent": {
       "title": "ClientDeleteEvent",
       "description": "Delete a message for yourself or for everyone.",
@@ -3213,6 +3679,64 @@
         "data"
       ]
     },
+    "ServerCallKeysEvent": {
+      "title": "ServerCallKeysEvent",
+      "description": "Sealed sender keys for this session (see docs/calls-e2ee.md). Sent only to the recipient session.",
+      "type": "object",
+      "properties": {
+        "type": {
+          "const": "call_keys"
+        },
+        "event_id": {
+          "$ref": "#/$defs/Id"
+        },
+        "chat_id": {
+          "$ref": "#/$defs/Id"
+        },
+        "data": {
+          "$ref": "#/$defs/CallKeyEnvelopeList"
+        }
+      },
+      "required": [
+        "type",
+        "event_id",
+        "chat_id",
+        "data"
+      ]
+    },
+    "ServerCallUpdatedEvent": {
+      "title": "ServerCallUpdatedEvent",
+      "description": "A call of the chat started, rang, changed participants or epoch, or ended. Carries the whole call; keep the one with the highest `version`. Sent to every member of the chat.",
+      "type": "object",
+      "properties": {
+        "type": {
+          "const": "call_updated"
+        },
+        "event_id": {
+          "$ref": "#/$defs/Id"
+        },
+        "chat_id": {
+          "$ref": "#/$defs/Id"
+        },
+        "data": {
+          "type": "object",
+          "properties": {
+            "call": {
+              "$ref": "#/$defs/Call"
+            }
+          },
+          "required": [
+            "call"
+          ]
+        }
+      },
+      "required": [
+        "type",
+        "event_id",
+        "chat_id",
+        "data"
+      ]
+    },
     "ServerChatCreatedEvent": {
       "title": "ServerChatCreatedEvent",
       "description": "A chat was created with you.",
@@ -3968,6 +4492,12 @@
         {
           "$ref": "#/$defs/ServerApprovalRequestCreatedEvent"
         },
+        {
+          "$ref": "#/$defs/ServerCallKeysEvent"
+        },
+        {
+          "$ref": "#/$defs/ServerCallUpdatedEvent"
+        },
         {
           "$ref": "#/$defs/ServerChatCreatedEvent"
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myronsi/messenger-api",
-  "version": "2.1.0-alpha.14",
+  "version": "2.1.0-alpha.15",
   "description": "API contract of the Messenger backend: OpenAPI document, WebSocket event schemas and generated TypeScript types",
   "license": "MIT",
   "repository": {