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

package/dist/ws-events.schema.json

@@ -484,7 +484,8 @@
             "required": [
               "id",
               "type",
-              "created_at"
+              "created_at",
+              "location"
             ],
             "properties": {
               "id": {
@@ -496,6 +497,24 @@
               "created_at": {
                 "type": "string",
                 "format": "date-time"
+              },
+              "user_agent": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "maxLength": 512
+              },
+              "location": {
+                "description": "Approximate location of the client when the event happened; `null` when unknown.",
+                "oneOf": [
+                  {
+                    "$ref": "#/$defs/Location"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
               }
             }
           }
@@ -509,17 +528,14 @@
         },
         {
           "type": "object",
-          "description": "Recovery parts of the temporary recovery flow (redesigned in release 1.1).",
+          "description": "The one-time recovery key shown after registration.",
           "properties": {
             "recovery_key": {
               "type": "string",
               "description": "Shown once; only a keyed hash is stored"
             },
-            "device_part": {
-              "type": "string"
-            },
-            "qr_part": {
-              "type": "string"
+            "username": {
+              "$ref": "#/$defs/Username"
             }
           }
         }
@@ -551,52 +567,6 @@
         }
       ]
     },
-    "RecoveryRequest": {
-      "type": "object",
-      "required": [
-        "username"
-      ],
-      "properties": {
-        "username": {
-          "$ref": "#/$defs/Username"
-        },
-        "device_part": {
-          "type": "string"
-        },
-        "qr_part": {
-          "type": "string"
-        }
-      }
-    },
-    "RecoveryResponse": {
-      "type": "object",
-      "required": [
-        "recovery_token"
-      ],
-      "properties": {
-        "recovery_token": {
-          "type": "string"
-        }
-      }
-    },
-    "ResetPasswordRequest": {
-      "type": "object",
-      "required": [
-        "recovery_token",
-        "new_password"
-      ],
-      "properties": {
-        "recovery_token": {
-          "type": "string"
-        },
-        "new_password": {
-          "type": "string",
-          "minLength": 8,
-          "maxLength": 128,
-          "writeOnly": true
-        }
-      }
-    },
     "WebSocketTicket": {
       "type": "object",
       "required": [
@@ -712,7 +682,8 @@
         "id",
         "created_at",
         "last_used_at",
-        "is_current"
+        "is_current",
+        "location"
       ],
       "properties": {
         "id": {
@@ -737,6 +708,50 @@
         },
         "is_current": {
           "type": "boolean"
+        },
+        "location": {
+          "description": "Approximate location of the device when it signed in or last refreshed its token; `null` when unknown.",
+          "oneOf": [
+            {
+              "$ref": "#/$defs/Location"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "Location": {
+      "type": "object",
+      "description": "Approximate location of a client address, looked up in an offline GeoIP database (IP geolocation by\nDB-IP, https://db-ip.com, CC BY 4.0). The address itself is never exposed. Each field is `null` when the\ndatabase does not know it; clients localise the country name from `country_code`.\n",
+      "required": [
+        "city",
+        "country_code",
+        "country"
+      ],
+      "properties": {
+        "city": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "City name in English"
+        },
+        "country_code": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^[A-Z]{2}$",
+          "description": "ISO 3166-1 alpha-2 country code"
+        },
+        "country": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Country name in English"
         }
       }
     },
@@ -785,8 +800,7 @@
     "DisableTwoFactorRequest": {
       "type": "object",
       "required": [
-        "password",
-        "code"
+        "password"
       ],
       "properties": {
         "password": {
@@ -2209,126 +2223,656 @@
         }
       }
     },
-    "ClientDeleteEvent": {
-      "title": "ClientDeleteEvent",
-      "description": "Delete a message for yourself or for everyone.",
+    "DeviceRecoveryStart": {
+      "type": "object",
+      "required": [
+        "username"
+      ],
+      "properties": {
+        "username": {
+          "$ref": "#/$defs/Username"
+        }
+      }
+    },
+    "DeviceRecoveryResult": {
       "type": "object",
+      "required": [
+        "request_id",
+        "match_number",
+        "expires_at"
+      ],
       "properties": {
-        "type": {
-          "const": "delete"
-        },
-        "client_temp_id": {
-          "$ref": "#/$defs/ClientTempId"
+        "request_id": {
+          "type": "string",
+          "minLength": 32,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9_-]+$"
         },
-        "chat_id": {
-          "$ref": "#/$defs/Id"
+        "match_number": {
+          "type": "integer",
+          "minimum": 10,
+          "maximum": 99
         },
-        "data": {
-          "type": "object",
-          "properties": {
-            "message_id": {
-              "$ref": "#/$defs/Id"
-            },
-            "scope": {
-              "type": "string",
-              "enum": [
-                "me",
-                "everyone"
-              ]
-            }
-          },
-          "required": [
-            "message_id",
-            "scope"
-          ],
-          "additionalProperties": false
+        "expires_at": {
+          "type": "string",
+          "format": "date-time"
         }
-      },
+      }
+    },
+    "DeviceRecoveryStatus": {
+      "type": "object",
       "required": [
-        "type",
-        "client_temp_id",
-        "chat_id",
-        "data"
+        "status"
       ],
-      "additionalProperties": false
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "pending",
+            "approved",
+            "denied",
+            "used",
+            "expired"
+          ]
+        }
+      }
     },
-    "ClientEditEvent": {
-      "title": "ClientEditEvent",
-      "description": "Edit your own text message or the caption of your file. An empty content removes a file's caption.",
+    "DeviceRecoveryApproval": {
       "type": "object",
+      "required": [
+        "match_number",
+        "password"
+      ],
       "properties": {
-        "type": {
-          "const": "edit"
-        },
-        "client_temp_id": {
-          "$ref": "#/$defs/ClientTempId"
+        "match_number": {
+          "type": "integer",
+          "minimum": 10,
+          "maximum": 99
         },
-        "chat_id": {
-          "$ref": "#/$defs/Id"
+        "password": {
+          "type": "string",
+          "maxLength": 1024
         },
-        "data": {
-          "type": "object",
-          "properties": {
-            "message_id": {
-              "$ref": "#/$defs/Id"
-            },
-            "content": {
-              "type": "string",
-              "maxLength": 4096
-            }
-          },
-          "required": [
-            "message_id",
-            "content"
-          ],
-          "additionalProperties": false
+        "code": {
+          "type": "string",
+          "maxLength": 128
         }
-      },
+      }
+    },
+    "DeviceRecoveryComplete": {
+      "type": "object",
       "required": [
-        "type",
-        "client_temp_id",
-        "chat_id",
-        "data"
+        "new_password"
       ],
-      "additionalProperties": false
+      "properties": {
+        "new_password": {
+          "type": "string",
+          "minLength": 8,
+          "maxLength": 128,
+          "writeOnly": true
+        }
+      }
     },
-    "ClientMessageEvent": {
-      "title": "ClientMessageEvent",
-      "description": "Send a message. Idempotent per `client_temp_id`; answered with `ack` or `error`.",
+    "QrLoginStatus": {
+      "type": "string",
+      "description": "`pending` until a signed-in device opens the request, `scanned` once it did, then `approved` or `denied`.\n`expired` when the request timed out or was used (only in poll answers).\n",
+      "enum": [
+        "pending",
+        "scanned",
+        "approved",
+        "denied",
+        "expired"
+      ]
+    },
+    "QrLoginStart": {
       "type": "object",
+      "required": [
+        "request_id",
+        "poll_token",
+        "url",
+        "expires_at"
+      ],
       "properties": {
-        "type": {
-          "const": "message"
+        "request_id": {
+          "type": "string",
+          "minLength": 32,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9_-]+$"
         },
-        "client_temp_id": {
-          "$ref": "#/$defs/ClientTempId"
+        "poll_token": {
+          "type": "string",
+          "minLength": 32,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9_-]+$",
+          "description": "Secret of the requesting device; only a keyed hash is stored."
         },
-        "chat_id": {
-          "$ref": "#/$defs/Id"
+        "url": {
+          "type": "string",
+          "description": "`<RECOVERY_WEB_URL>/qr/<request_id>`, the content of the QR code."
         },
-        "data": {
+        "expires_at": {
+          "$ref": "#/$defs/Timestamp"
+        }
+      }
+    },
+    "QrLoginRequest": {
+      "type": "object",
+      "required": [
+        "request_id",
+        "status",
+        "device",
+        "location",
+        "created_at",
+        "expires_at"
+      ],
+      "properties": {
+        "request_id": {
+          "type": "string"
+        },
+        "status": {
+          "$ref": "#/$defs/QrLoginStatus"
+        },
+        "device": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "maxLength": 512,
+          "description": "User agent of the device that asks to sign in; `null` when it sent none."
+        },
+        "location": {
+          "description": "Approximate location of the device that asks to sign in; `null` when unknown.",
           "oneOf": [
             {
-              "type": "object",
-              "title": "TextMessageData",
-              "properties": {
-                "type": {
-                  "const": "text"
-                },
-                "content": {
-                  "type": "string",
-                  "minLength": 1,
-                  "maxLength": 4096
-                },
-                "reply_to": {
-                  "oneOf": [
-                    {
-                      "$ref": "#/$defs/Id"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ]
+              "$ref": "#/$defs/Location"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "created_at": {
+          "$ref": "#/$defs/Timestamp"
+        },
+        "expires_at": {
+          "$ref": "#/$defs/Timestamp"
+        }
+      }
+    },
+    "QrLoginPollRequest": {
+      "type": "object",
+      "required": [
+        "poll_token"
+      ],
+      "properties": {
+        "poll_token": {
+          "type": "string",
+          "maxLength": 128,
+          "writeOnly": true
+        }
+      }
+    },
+    "QrLoginPollResult": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "status"
+          ],
+          "properties": {
+            "status": {
+              "type": "string",
+              "enum": [
+                "pending",
+                "scanned",
+                "denied",
+                "expired"
+              ]
+            }
+          }
+        },
+        {
+          "allOf": [
+            {
+              "$ref": "#/$defs/TokenResponse"
+            },
+            {
+              "type": "object",
+              "required": [
+                "status"
+              ],
+              "properties": {
+                "status": {
+                  "type": "string",
+                  "const": "approved"
+                }
+              }
+            }
+          ]
+        }
+      ]
+    },
+    "QrLoginApproval": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "string",
+          "maxLength": 128,
+          "description": "An authenticator code or an unused recovery code; required when two-factor is on."
+        }
+      }
+    },
+    "PasskeyOptions": {
+      "type": "object",
+      "required": [
+        "challenge_id",
+        "public_key"
+      ],
+      "properties": {
+        "challenge_id": {
+          "type": "string",
+          "minLength": 32,
+          "maxLength": 128
+        },
+        "public_key": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      }
+    },
+    "PasskeyRegistration": {
+      "type": "object",
+      "required": [
+        "password",
+        "name"
+      ],
+      "properties": {
+        "password": {
+          "type": "string",
+          "maxLength": 128,
+          "writeOnly": true
+        },
+        "code": {
+          "type": "string",
+          "maxLength": 128
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64
+        }
+      }
+    },
+    "PasskeyVerification": {
+      "type": "object",
+      "required": [
+        "challenge_id",
+        "credential"
+      ],
+      "properties": {
+        "challenge_id": {
+          "type": "string",
+          "minLength": 32,
+          "maxLength": 128
+        },
+        "credential": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      }
+    },
+    "PasskeyLoginOptions": {
+      "type": "object",
+      "required": [],
+      "properties": {
+        "username": {
+          "$ref": "#/$defs/Username"
+        }
+      }
+    },
+    "PasskeyRename": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64
+        }
+      }
+    },
+    "PasskeyRemoval": {
+      "type": "object",
+      "required": [],
+      "properties": {
+        "password": {
+          "type": "string",
+          "maxLength": 128,
+          "writeOnly": true
+        }
+      }
+    },
+    "Passkey": {
+      "type": "object",
+      "required": [
+        "id",
+        "name",
+        "created_at",
+        "last_used_at"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "last_used_at": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time"
+        }
+      }
+    },
+    "PasskeyPage": {
+      "type": "object",
+      "required": [
+        "items"
+      ],
+      "properties": {
+        "items": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Passkey"
+          }
+        }
+      }
+    },
+    "RecoveryEmailStatus": {
+      "type": "object",
+      "required": [
+        "address",
+        "state",
+        "enabled"
+      ],
+      "properties": {
+        "address": {
+          "type": "string"
+        },
+        "state": {
+          "type": "string",
+          "enum": [
+            "not_added",
+            "pending",
+            "verified"
+          ]
+        },
+        "enabled": {
+          "type": "boolean"
+        }
+      }
+    },
+    "RecoveryOverview": {
+      "type": "object",
+      "required": [
+        "recovery_key",
+        "other_devices",
+        "passkeys",
+        "passkeys_enabled",
+        "email"
+      ],
+      "properties": {
+        "recovery_key": {
+          "$ref": "#/$defs/RecoveryKeyStatus"
+        },
+        "other_devices": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "passkeys": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "passkeys_enabled": {
+          "type": "boolean"
+        },
+        "email": {
+          "$ref": "#/$defs/RecoveryEmailStatus"
+        }
+      }
+    },
+    "SetRecoveryEmail": {
+      "type": "object",
+      "required": [
+        "email",
+        "password"
+      ],
+      "properties": {
+        "email": {
+          "type": "string",
+          "format": "email",
+          "maxLength": 254
+        },
+        "password": {
+          "type": "string",
+          "minLength": 8,
+          "maxLength": 128,
+          "writeOnly": true
+        },
+        "code": {
+          "type": "string",
+          "maxLength": 128
+        }
+      }
+    },
+    "RemoveRecoveryEmail": {
+      "type": "object",
+      "required": [
+        "password"
+      ],
+      "properties": {
+        "password": {
+          "type": "string",
+          "minLength": 8,
+          "maxLength": 128,
+          "writeOnly": true
+        },
+        "code": {
+          "type": "string",
+          "maxLength": 128
+        }
+      }
+    },
+    "VerifyRecoveryEmail": {
+      "type": "object",
+      "required": [
+        "token"
+      ],
+      "properties": {
+        "token": {
+          "type": "string",
+          "minLength": 32,
+          "maxLength": 128
+        }
+      }
+    },
+    "EmailResetRequest": {
+      "type": "object",
+      "required": [
+        "username_or_email"
+      ],
+      "properties": {
+        "username_or_email": {
+          "type": "string",
+          "maxLength": 254
+        }
+      }
+    },
+    "EmailResetConfirmation": {
+      "type": "object",
+      "required": [
+        "token",
+        "new_password"
+      ],
+      "properties": {
+        "token": {
+          "type": "string",
+          "minLength": 32,
+          "maxLength": 128
+        },
+        "new_password": {
+          "type": "string",
+          "minLength": 8,
+          "maxLength": 128,
+          "writeOnly": true
+        },
+        "code": {
+          "type": "string",
+          "maxLength": 128
+        }
+      }
+    },
+    "EmailResetAccepted": {
+      "type": "object",
+      "required": [
+        "message"
+      ],
+      "properties": {
+        "message": {
+          "type": "string"
+        }
+      }
+    },
+    "ClientDeleteEvent": {
+      "title": "ClientDeleteEvent",
+      "description": "Delete a message for yourself or for everyone.",
+      "type": "object",
+      "properties": {
+        "type": {
+          "const": "delete"
+        },
+        "client_temp_id": {
+          "$ref": "#/$defs/ClientTempId"
+        },
+        "chat_id": {
+          "$ref": "#/$defs/Id"
+        },
+        "data": {
+          "type": "object",
+          "properties": {
+            "message_id": {
+              "$ref": "#/$defs/Id"
+            },
+            "scope": {
+              "type": "string",
+              "enum": [
+                "me",
+                "everyone"
+              ]
+            }
+          },
+          "required": [
+            "message_id",
+            "scope"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "type",
+        "client_temp_id",
+        "chat_id",
+        "data"
+      ],
+      "additionalProperties": false
+    },
+    "ClientEditEvent": {
+      "title": "ClientEditEvent",
+      "description": "Edit your own text message or the caption of your file. An empty content removes a file's caption.",
+      "type": "object",
+      "properties": {
+        "type": {
+          "const": "edit"
+        },
+        "client_temp_id": {
+          "$ref": "#/$defs/ClientTempId"
+        },
+        "chat_id": {
+          "$ref": "#/$defs/Id"
+        },
+        "data": {
+          "type": "object",
+          "properties": {
+            "message_id": {
+              "$ref": "#/$defs/Id"
+            },
+            "content": {
+              "type": "string",
+              "maxLength": 4096
+            }
+          },
+          "required": [
+            "message_id",
+            "content"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "type",
+        "client_temp_id",
+        "chat_id",
+        "data"
+      ],
+      "additionalProperties": false
+    },
+    "ClientMessageEvent": {
+      "title": "ClientMessageEvent",
+      "description": "Send a message. Idempotent per `client_temp_id`; answered with `ack` or `error`.",
+      "type": "object",
+      "properties": {
+        "type": {
+          "const": "message"
+        },
+        "client_temp_id": {
+          "$ref": "#/$defs/ClientTempId"
+        },
+        "chat_id": {
+          "$ref": "#/$defs/Id"
+        },
+        "data": {
+          "oneOf": [
+            {
+              "type": "object",
+              "title": "TextMessageData",
+              "properties": {
+                "type": {
+                  "const": "text"
+                },
+                "content": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 4096
+                },
+                "reply_to": {
+                  "oneOf": [
+                    {
+                      "$ref": "#/$defs/Id"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
                 }
               },
               "required": [
@@ -3185,6 +3729,136 @@
         "data"
       ]
     },
+    "ServerRecoveryRequestEvent": {
+      "title": "ServerRecoveryRequestEvent",
+      "type": "object",
+      "required": [
+        "type",
+        "event_id",
+        "chat_id",
+        "data"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "const": "recovery_request"
+        },
+        "event_id": {
+          "type": "string",
+          "pattern": "^[0-9]+$"
+        },
+        "chat_id": {
+          "type": "null"
+        },
+        "data": {
+          "type": "object",
+          "required": [
+            "request_id",
+            "user_agent",
+            "location",
+            "choices",
+            "expires_at"
+          ],
+          "properties": {
+            "request_id": {
+              "description": "Approval handle for POST /auth/recovery-requests/{requestId}/approve and /deny. It is not the requester's capability.",
+              "type": "string",
+              "minLength": 32,
+              "maxLength": 128,
+              "pattern": "^[A-Za-z0-9_-]+$"
+            },
+            "user_agent": {
+              "type": "string"
+            },
+            "location": {
+              "oneOf": [
+                {
+                  "$ref": "#/$defs/Location"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "choices": {
+              "type": "array",
+              "minItems": 3,
+              "maxItems": 3,
+              "uniqueItems": true,
+              "items": {
+                "type": "integer",
+                "minimum": 10,
+                "maximum": 99
+              }
+            },
+            "expires_at": {
+              "type": "string",
+              "format": "date-time"
+            }
+          }
+        }
+      }
+    },
+    "ServerSecurityAlertEvent": {
+      "title": "ServerSecurityAlertEvent",
+      "type": "object",
+      "required": [
+        "type",
+        "event_id",
+        "chat_id",
+        "data"
+      ],
+      "properties": {
+        "type": {
+          "const": "security_alert"
+        },
+        "event_id": {
+          "$ref": "#/$defs/Id"
+        },
+        "chat_id": {
+          "type": "null"
+        },
+        "data": {
+          "type": "object",
+          "required": [
+            "type"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "password_changed",
+                "recovery_key_changed",
+                "2fa_enabled",
+                "2fa_disabled",
+                "passkey_added",
+                "passkey_removed",
+                "recovery_email_changed",
+                "recovery_email_removed",
+                "passkey_counter_warning",
+                "login",
+                "login_2fa",
+                "passkey_login",
+                "qr_login_approved"
+              ]
+            },
+            "user_agent": {
+              "type": "string",
+              "maxLength": 512
+            },
+            "created_at": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "session_id": {
+              "description": "The session that made the change, when a signed-in session made it. Clients skip alerts for their own session.",
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        }
+      }
+    },
     "ServerSecurityNoticeEvent": {
       "title": "ServerSecurityNoticeEvent",
       "type": "object",
@@ -3336,6 +4010,12 @@
         {
           "$ref": "#/$defs/ServerReadEvent"
         },
+        {
+          "$ref": "#/$defs/ServerRecoveryRequestEvent"
+        },
+        {
+          "$ref": "#/$defs/ServerSecurityAlertEvent"
+        },
         {
           "$ref": "#/$defs/ServerSecurityNoticeEvent"
         },