supernote.models.auth

  1"""Module for authentication API data models.
  2
  3The following endpoints are supported:
  4- /api/official/user/account/login/equipment
  5- /api/official/user/account/login/new
  6- /api/official/user/query/random/code
  7- /api/official/user/sms/login
  8- /api/user/sms/validcode/send
  9- /api/user/query/token
 10- /api/user/validcode/pre-auth
 11- /api/user/logout (empty body)
 12"""
 13
 14from dataclasses import dataclass, field
 15
 16from mashumaro import field_options
 17from mashumaro.config import BaseConfig
 18from mashumaro.mixins.json import DataClassJSONMixin
 19
 20from .base import BaseEnum, BaseResponse
 21
 22COUNTRY_CODE = 1
 23BROWSER = "Chrome142"
 24LANGUAGE = "en"
 25
 26
 27class Equipment(BaseEnum):
 28    """Device type."""
 29
 30    WEB = 1
 31    APP = 2
 32    TERMINAL = 3
 33    USER_PLATFORM = 4
 34
 35
 36def _deserialize_int_equipment(value: str) -> Equipment:
 37    return Equipment(int(value))
 38
 39
 40@dataclass
 41class UserCheckDTO(DataClassJSONMixin):
 42    """Request to check user existence."""
 43
 44    email: str
 45    country_code: str = field(metadata=field_options(alias="countryCode"), default="")
 46    telephone: str = ""
 47    user_name: str = field(metadata=field_options(alias="userName"), default="")
 48    domain: str = ""
 49
 50    class Config(BaseConfig):
 51        serialize_by_alias = True
 52
 53
 54class LoginMethod(str, BaseEnum):
 55    """Method for logging in to account."""
 56
 57    PHONE = "1"
 58    EMAIL = "2"
 59    WECHAT = "3"
 60
 61
 62@dataclass
 63class LoginDTO(DataClassJSONMixin):
 64    """Request to login.
 65
 66    This is used by the following POST endpoints:
 67        /api/official/user/account/login/equipment
 68        /api/official/user/account/login/new
 69    """
 70
 71    account: str
 72    """User account (must be an email address)."""
 73
 74    password: str
 75    """Hashed password. Schema: SHA256(MD5(pwd) + randomCode)) or MD5(pwd + randomCode)."""
 76
 77    timestamp: str
 78    """Client timestamp in milliseconds."""
 79
 80    login_method: LoginMethod = field(metadata=field_options(alias="loginMethod"))
 81    """Login method."""
 82
 83    language: str = LANGUAGE
 84    """Language code."""
 85
 86    country_code: int | None = field(
 87        metadata=field_options(alias="countryCode"), default=None
 88    )
 89    """Country code."""
 90
 91    browser: str = BROWSER
 92    """Browser name (user agent info)."""
 93
 94    equipment: Equipment = field(
 95        metadata=field_options(deserialize=_deserialize_int_equipment),
 96        default=Equipment.WEB,
 97    )
 98    """Device type."""
 99
100    equipment_no: str | None = field(
101        metadata=field_options(alias="equipmentNo"), default=None
102    )
103    """Device serial number (SN12345678) or other client identifier (WEB)."""
104
105    class Config(BaseConfig):
106        serialize_by_alias = True
107
108
109@dataclass(kw_only=True)
110class LoginVO(BaseResponse):
111    """Response from login endpoints."""
112
113    token: str
114    """JWT Access Token."""
115
116    counts: str
117    """Error count."""
118
119    user_name: str | None = field(
120        metadata=field_options(alias="userName"), default=None
121    )
122    """User nickname."""
123
124    is_bind: str = field(metadata=field_options(alias="isBind"), default="N")
125    """Is account bound."""
126
127    is_bind_equipment: str = field(
128        metadata=field_options(alias="isBindEquipment"), default="N"
129    )
130    """Is device bound (Terminal only)."""
131
132    sold_out_count: int = field(metadata=field_options(alias="soldOutCount"), default=0)
133    """Logout count."""
134
135
136@dataclass
137class RandomCodeDTO(DataClassJSONMixin):
138    """Request to get a random code.
139
140    This is used by the following POST endpoint:
141        /api/official/user/query/random/code
142    """
143
144    account: str
145    """User account (must be an email address)."""
146
147    country_code: int | None = field(
148        metadata=field_options(alias="countryCode"), default=None
149    )
150    """Country code."""
151
152    version: str | None = None
153    """Version."""
154
155    class Config(BaseConfig):
156        serialize_by_alias = True
157
158
159@dataclass(kw_only=True)
160class RandomCodeVO(BaseResponse):
161    """Response from random code endpoint."""
162
163    random_code: str = field(metadata=field_options(alias="randomCode"), default="")
164    """Server-side nonce (salt) used for password hashing."""
165
166    timestamp: str = ""
167    """Client timestamp in milliseconds."""
168
169
170@dataclass
171class QueryTokenDTO(DataClassJSONMixin):
172    """Request to token endpoint.
173
174    This is used by the following POST endpoint:
175        /api/user/query/token
176    """
177
178
179@dataclass(kw_only=True)
180class QueryTokenVO(BaseResponse):
181    """Response from token endpoint."""
182
183    token: str | None = None
184    """JWT Access Token."""
185
186    class Config(BaseConfig):
187        serialize_by_alias = True
188        omit_none = False
189        code_generation_options = ["TO_DICT_ADD_OMIT_NONE_FLAG"]
190
191
192class OSType(str, BaseEnum):
193    """OS Type."""
194
195    WINDOWS = "WINDOWS"
196    MACOS = "MACOS"
197    LINUX = "LINUX"
198    ANDROID = "ANDROID"
199    IOS = "IOS"
200
201
202@dataclass
203class UserVO(DataClassJSONMixin):
204    """User profile VO."""
205
206    user_id: int = field(metadata=field_options(alias="userId"), default=0)
207    user_name: str | None = field(
208        metadata=field_options(alias="userName"), default=None
209    )
210    email: str | None = None
211    phone: str | None = None
212    country_code: str | None = field(
213        metadata=field_options(alias="countryCode"), default=None
214    )
215    total_capacity: str = field(
216        metadata=field_options(alias="totalCapacity"), default="0"
217    )
218    file_server: str = field(metadata=field_options(alias="fileServer"), default="0")
219    avatars_url: str | None = field(
220        metadata=field_options(alias="avatarsUrl"), default=None
221    )
222    birthday: str | None = None
223    sex: str | None = None
224
225    class Config(BaseConfig):
226        serialize_by_alias = True
227        omit_none = True
228        code_generation_options = ["TO_DICT_ADD_OMIT_NONE_FLAG"]
229
230
231@dataclass
232class SmsLoginDTO(DataClassJSONMixin):
233    """Request to login via sms.
234
235    This is used by the following POST endpoint:
236        /api/user/sms/login
237    """
238
239    valid_code: str = field(metadata=field_options(alias="validCode"))
240    """SMS/Email verification code."""
241
242    valid_code_key: str = field(metadata=field_options(alias="validCodeKey"))
243    """Redis session key for the code (e.g., '{email}_validCode')."""
244
245    country_code: int = field(
246        metadata=field_options(alias="countryCode"), default=COUNTRY_CODE
247    )
248
249    telephone: str | None = None
250    """User phone number."""
251
252    timestamp: str | None = None
253    """Client timestamp in milliseconds."""
254
255    email: str | None = None
256    """User email."""
257
258    browser: str = BROWSER
259    """Browser name (user agent info)."""
260
261    equipment: Equipment = Equipment.WEB
262    """Device type."""
263
264    devices: OSType | None = OSType.WINDOWS
265    """OS Type: WINDOWS, MACOS, LINUX, ANDROID, IOS."""
266
267    class Config(BaseConfig):
268        serialize_by_alias = True
269
270
271@dataclass(kw_only=True)
272class SmsLoginVO(BaseResponse):
273    """Response from access token call."""
274
275    token: str
276
277
278@dataclass
279class UserPreAuthRequest(DataClassJSONMixin):
280    """Request for pre-auth.
281
282    This is used by the following POST endpoint:
283        /api/user/validcode/pre-auth
284    """
285
286    account: str
287
288
289@dataclass
290class UserPreAuthResponse(BaseResponse):
291    """Response from pre-auth."""
292
293    token: str = ""
294
295
296@dataclass
297class SendSmsDTO(DataClassJSONMixin):
298    """Request to send SMS code.
299
300    This is used by the following POST endpoint:
301        /api/user/sms/validcode/send
302    """
303
304    telephone: str
305    """User phone number."""
306
307    timestamp: str
308    """Client timestamp in milliseconds."""
309
310    token: str
311    """JWT Access Token."""
312
313    sign: str
314    """JWT Signature."""
315
316    extend: str | None = None
317    """JWT Extension."""
318
319    nationcode: int = field(
320        metadata=field_options(alias="nationcode"), default=COUNTRY_CODE
321    )
322    """Country code."""
323
324    class Config(BaseConfig):
325        serialize_by_alias = True
326
327
328@dataclass
329class SendSmsVO(BaseResponse):
330    """Response from send SMS."""
331
332    valid_code_key: str = field(
333        metadata=field_options(alias="validCodeKey"), default=""
334    )
335
336
337@dataclass
338class EmailDTO(DataClassJSONMixin):
339    """Request to send email code.
340
341    Used by:
342        /api/user/mail/validcode (POST)
343    """
344
345    email: str
346    """User email."""
347
348    language: str | None = None
349    """Language code."""
350
351    class Config(BaseConfig):
352        serialize_by_alias = True
353
354
355@dataclass
356class ValidCodeDTO(DataClassJSONMixin):
357    """Request to check validation code.
358
359    Used by:
360        /api/user/check/validcode (POST)
361    """
362
363    valid_code_key: str = field(metadata=field_options(alias="validCodeKey"))
364    """Key for the validation code."""
365
366    valid_code: str = field(metadata=field_options(alias="validCode"))
367    """The validation code."""
368
369    class Config(BaseConfig):
370        serialize_by_alias = True