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_name: str | None = field(
207        metadata=field_options(alias="userName"), default=None
208    )
209    email: str | None = None
210    phone: str | None = None
211    country_code: str | None = field(
212        metadata=field_options(alias="countryCode"), default=None
213    )
214    total_capacity: str = field(
215        metadata=field_options(alias="totalCapacity"), default="0"
216    )
217    file_server: str = field(metadata=field_options(alias="fileServer"), default="0")
218    avatars_url: str | None = field(
219        metadata=field_options(alias="avatarsUrl"), default=None
220    )
221    birthday: str | None = None
222    sex: str | None = None
223
224    class Config(BaseConfig):
225        serialize_by_alias = True
226        omit_none = True
227        code_generation_options = ["TO_DICT_ADD_OMIT_NONE_FLAG"]
228
229
230@dataclass
231class UserQueryByIdVO(BaseResponse):
232    """User query response."""
233
234    user: UserVO | None = None
235    is_user: bool = field(metadata=field_options(alias="isUser"), default=False)
236    equipment_no: str | None = field(
237        metadata=field_options(alias="equipmentNo"), default=None
238    )
239
240
241@dataclass
242class SmsLoginDTO(DataClassJSONMixin):
243    """Request to login via sms.
244
245    This is used by the following POST endpoint:
246        /api/user/sms/login
247    """
248
249    valid_code: str = field(metadata=field_options(alias="validCode"))
250    """SMS/Email verification code."""
251
252    valid_code_key: str = field(metadata=field_options(alias="validCodeKey"))
253    """Redis session key for the code (e.g., '{email}_validCode')."""
254
255    country_code: int = field(
256        metadata=field_options(alias="countryCode"), default=COUNTRY_CODE
257    )
258
259    telephone: str | None = None
260    """User phone number."""
261
262    timestamp: str | None = None
263    """Client timestamp in milliseconds."""
264
265    email: str | None = None
266    """User email."""
267
268    browser: str = BROWSER
269    """Browser name (user agent info)."""
270
271    equipment: Equipment = Equipment.WEB
272    """Device type."""
273
274    devices: OSType | None = OSType.WINDOWS
275    """OS Type: WINDOWS, MACOS, LINUX, ANDROID, IOS."""
276
277    class Config(BaseConfig):
278        serialize_by_alias = True
279
280
281@dataclass(kw_only=True)
282class SmsLoginVO(BaseResponse):
283    """Response from access token call."""
284
285    token: str
286
287
288@dataclass
289class UserPreAuthRequest(DataClassJSONMixin):
290    """Request for pre-auth.
291
292    This is used by the following POST endpoint:
293        /api/user/validcode/pre-auth
294    """
295
296    account: str
297
298
299@dataclass
300class UserPreAuthResponse(BaseResponse):
301    """Response from pre-auth."""
302
303    token: str = ""
304
305
306@dataclass
307class SendSmsDTO(DataClassJSONMixin):
308    """Request to send SMS code.
309
310    This is used by the following POST endpoint:
311        /api/user/sms/validcode/send
312    """
313
314    telephone: str
315    """User phone number."""
316
317    timestamp: str
318    """Client timestamp in milliseconds."""
319
320    token: str
321    """JWT Access Token."""
322
323    sign: str
324    """JWT Signature."""
325
326    extend: str | None = None
327    """JWT Extension."""
328
329    nationcode: int = field(
330        metadata=field_options(alias="nationcode"), default=COUNTRY_CODE
331    )
332    """Country code."""
333
334    class Config(BaseConfig):
335        serialize_by_alias = True
336
337
338@dataclass
339class SendSmsVO(BaseResponse):
340    """Response from send SMS."""
341
342    valid_code_key: str = field(
343        metadata=field_options(alias="validCodeKey"), default=""
344    )
345
346
347@dataclass
348class EmailDTO(DataClassJSONMixin):
349    """Request to send email code.
350
351    Used by:
352        /api/user/mail/validcode (POST)
353    """
354
355    email: str
356    """User email."""
357
358    language: str | None = None
359    """Language code."""
360
361    class Config(BaseConfig):
362        serialize_by_alias = True
363
364
365@dataclass
366class ValidCodeDTO(DataClassJSONMixin):
367    """Request to check validation code.
368
369    Used by:
370        /api/user/check/validcode (POST)
371    """
372
373    valid_code_key: str = field(metadata=field_options(alias="validCodeKey"))
374    """Key for the validation code."""
375
376    valid_code: str = field(metadata=field_options(alias="validCode"))
377    """The validation code."""
378
379    class Config(BaseConfig):
380        serialize_by_alias = True