@hexlet/frontend-blog-server 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,49 @@
1
- # Temporary Holding Version
1
+ # @hexlet/frontend-blog-server
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Готовый бэкенд для проекта «Блог». Писать его не нужно, вы подключаете пакет к своему фронтенду и работаете с настоящим API.
4
+
5
+ Сервер написан на Fastify 5 и держит данные в памяти. При каждом старте он загружает сид, поэтому после перезапуска блог возвращается к исходному состоянию.
6
+
7
+ ## Запуск
8
+
9
+ ```bash
10
+ npx frontend-blog-server start # API на :8080
11
+ npx frontend-blog-server start -p 3000 # другой порт
12
+ npx frontend-blog-server start -s ./dist # API и собранный SPA из ./dist
13
+ ```
14
+
15
+ С флагом `-s` сервер раздаёт сборку по `/` и API по `/api`, так что фронтенд и API живут на одном origin. На любой путь вне `/api` сервер отдаёт `index.html`, и клиентский роутинг работает при прямом заходе по адресу. Порт берётся из `-p`, затем из переменной `PORT`, иначе 8080.
16
+
17
+ ## Контракт API
18
+
19
+ ```bash
20
+ npx frontend-blog-server contract # openapi.yaml и main.tsp в ./contract
21
+ npx frontend-blog-server contract api # в указанный каталог
22
+ ```
23
+
24
+ `openapi.yaml` описывает все эндпоинты, тела запросов и ответов и коды ошибок. Типы для фронтенда из него генерирует `openapi-typescript`.
25
+
26
+ ## Сид
27
+
28
+ | Что | Значение |
29
+ | --- | --- |
30
+ | Пользователи | `alice`, `bob`, `carol`, пароль у всех `password` |
31
+ | Категории | `frontend`, `backend`, `devops`, `design`, `career`, `news` |
32
+ | Статьи | 30 на русском и английском. У самой новой два комментария (ответ на ответ) и два лайка |
33
+
34
+ ## Авторизация
35
+
36
+ `POST /api/users` (регистрация) и `POST /api/session` (вход) возвращают `token`. Его передают в заголовке `Authorization: Bearer <token>`. Токен живёт, пока работает сервер.
37
+
38
+ ## Ошибки
39
+
40
+ Ошибка приходит телом `{ code, message }`. `code` машинный (`validation_error`, `unauthorized`, `forbidden`, `not_found`, `username_taken`, `invalid_credentials`), текст для пользователя фронтенд берёт из своих переводов по коду. `message` по-английски и нужен разработчику.
41
+
42
+ ## Разработка пакета
43
+
44
+ ```bash
45
+ npm ci
46
+ npm test # тесты API
47
+ npm run gen:types # src/generated/api.ts из contract/openapi.yaml
48
+ cd contract && npm ci && npm run compile # openapi.yaml из main.tsp
49
+ ```
@@ -0,0 +1,286 @@
1
+ import "@typespec/http";
2
+ import "@typespec/openapi";
3
+ import "@typespec/openapi3";
4
+
5
+ using TypeSpec.Http;
6
+ using TypeSpec.OpenAPI;
7
+
8
+ @service(#{ title: "Blog API" })
9
+ @info(#{ version: "1.0.0" })
10
+ @server("http://localhost:8080", "Local development")
11
+ @doc("Токен из POST /api/session или POST /api/users в заголовке Authorization: Bearer <token>.")
12
+ namespace BlogApi;
13
+
14
+ // ---------- Ошибки ----------
15
+
16
+ @doc("""
17
+ Ошибка API. code — машинный код без текста на конкретном языке, сообщение для
18
+ пользователя фронтенд берёт из своих переводов по коду. message — подсказка
19
+ разработчику на английском.
20
+ """)
21
+ @example(#{ code: "validation_error", message: "title must not be empty" })
22
+ @error
23
+ model ApiError {
24
+ code:
25
+ | "validation_error"
26
+ | "unauthorized"
27
+ | "forbidden"
28
+ | "not_found"
29
+ | "username_taken"
30
+ | "invalid_credentials";
31
+ message: string;
32
+ }
33
+
34
+ model BadRequest {
35
+ @statusCode _: 400;
36
+ @body body: ApiError;
37
+ }
38
+
39
+ model Unauthorized {
40
+ @statusCode _: 401;
41
+ @body body: ApiError;
42
+ }
43
+
44
+ model Forbidden {
45
+ @statusCode _: 403;
46
+ @body body: ApiError;
47
+ }
48
+
49
+ model NotFound {
50
+ @statusCode _: 404;
51
+ @body body: ApiError;
52
+ }
53
+
54
+ model Conflict {
55
+ @statusCode _: 409;
56
+ @body body: ApiError;
57
+ }
58
+
59
+ // ---------- Пользователи и сессия ----------
60
+
61
+ @doc("Публичные данные пользователя.")
62
+ @example(#{ id: 1, username: "alice" })
63
+ model User {
64
+ id: int32;
65
+ username: string;
66
+ }
67
+
68
+ @doc("Логин и пароль. username: 3–20 символов из латиницы, цифр, _ и -; password: от 6 символов.")
69
+ @example(#{ username: "alice", password: "password" })
70
+ model Credentials {
71
+ username: string;
72
+ password: string;
73
+ }
74
+
75
+ @doc("Ответ на вход и регистрацию. token передаётся в заголовке Authorization: Bearer <token>.")
76
+ model Session {
77
+ token: string;
78
+ user: User;
79
+ }
80
+
81
+ @doc("Профиль автора.")
82
+ model Profile {
83
+ ...User;
84
+ articlesCount: int32;
85
+ }
86
+
87
+ // ---------- Категории ----------
88
+
89
+ @doc("""
90
+ Категория. Список статический и задаётся сидом. slug стабилен и годится для URL и
91
+ ключей перевода, name — название по-английски.
92
+ """)
93
+ @example(#{ id: 1, slug: "frontend", name: "Frontend" })
94
+ model Category {
95
+ id: int32;
96
+ slug: string;
97
+ name: string;
98
+ }
99
+
100
+ // ---------- Статьи ----------
101
+
102
+ @doc("Статья в ленте. body в ленте не приходит, только excerpt — начало текста без разметки Markdown.")
103
+ model ArticleSummary {
104
+ id: int32;
105
+ title: string;
106
+ excerpt: string;
107
+ category: Category;
108
+ author: User;
109
+ createdAt: utcDateTime;
110
+ likesCount: int32;
111
+ commentsCount: int32;
112
+ }
113
+
114
+ @doc("""
115
+ Статья целиком. body — исходный Markdown, его рендерит фронтенд.
116
+ liked — поставил ли лайк текущий пользователь; для гостя всегда false.
117
+ """)
118
+ model Article {
119
+ ...ArticleSummary;
120
+ body: string;
121
+ updatedAt: utcDateTime;
122
+ liked: boolean;
123
+ }
124
+
125
+ @doc("Страница ленты.")
126
+ model ArticlePage {
127
+ items: ArticleSummary[];
128
+ page: int32;
129
+ perPage: int32;
130
+ total: int32;
131
+ }
132
+
133
+ @doc("Данные для создания статьи. title: 1–120 символов, body: непустой.")
134
+ model ArticleInput {
135
+ title: string;
136
+ body: string;
137
+ categoryId: int32;
138
+ }
139
+
140
+ @doc("Правка статьи: передаются только меняющиеся поля.")
141
+ model ArticlePatch {
142
+ title?: string;
143
+ body?: string;
144
+ categoryId?: int32;
145
+ }
146
+
147
+ // ---------- Комментарии ----------
148
+
149
+ @doc("""
150
+ Комментарий. Список приходит плоским, по возрастанию createdAt; дерево фронтенд
151
+ собирает сам по parentId. parentId = null у ответа на саму статью.
152
+ """)
153
+ model Comment {
154
+ id: int32;
155
+ body: string;
156
+ parentId: int32 | null;
157
+ author: User;
158
+ createdAt: utcDateTime;
159
+ }
160
+
161
+ @doc("Новый комментарий. parentId — комментарий той же статьи, на который это ответ.")
162
+ model CommentInput {
163
+ body: string;
164
+ parentId?: int32 | null;
165
+ }
166
+
167
+ @doc("Состояние лайка после изменения.")
168
+ model LikeState {
169
+ liked: boolean;
170
+ likesCount: int32;
171
+ }
172
+
173
+ // ---------- Маршруты ----------
174
+
175
+ @route("/api/health")
176
+ @tag("System")
177
+ interface Health {
178
+ @get check(): { status: "ok" };
179
+ }
180
+
181
+ @route("/api/users")
182
+ @tag("Users")
183
+ interface Users {
184
+ @doc("Регистрация. Сразу возвращает сессию.")
185
+ @post
186
+ signup(@body body: Credentials): {
187
+ @statusCode _: 201;
188
+ @body body: Session;
189
+ } | BadRequest | Conflict;
190
+
191
+ @doc("Профиль автора по имени.")
192
+ @get
193
+ @route("/{username}")
194
+ profile(@path username: string): Profile | NotFound;
195
+ }
196
+
197
+ @route("/api/session")
198
+ @tag("Session")
199
+ interface SessionRoutes {
200
+ @doc("Вход.")
201
+ @post
202
+ login(@body body: Credentials): Session | BadRequest | Unauthorized;
203
+ }
204
+
205
+ @route("/api/me")
206
+ @tag("Session")
207
+ interface Me {
208
+ @doc("Текущий пользователь по токену.")
209
+ @get
210
+ @useAuth(BearerAuth)
211
+ me(): User | Unauthorized;
212
+ }
213
+
214
+ @route("/api/categories")
215
+ @tag("Categories")
216
+ interface Categories {
217
+ @get list(): Category[];
218
+ }
219
+
220
+ @route("/api/articles")
221
+ @tag("Articles")
222
+ interface Articles {
223
+ @doc("Лента, новые статьи первыми.")
224
+ @get
225
+ list(
226
+ @query page?: int32 = 1,
227
+ @doc("От 1 до 50.") @query perPage?: int32 = 10,
228
+ @doc("slug категории.") @query category?: string,
229
+ @doc("username автора.") @query author?: string,
230
+ ): ArticlePage | BadRequest;
231
+
232
+ @get
233
+ @route("/{id}")
234
+ @doc("С токеном поле liked показывает лайк текущего пользователя.")
235
+ @useAuth(BearerAuth | NoAuth)
236
+ read(@path id: int32): Article | NotFound;
237
+
238
+ @post
239
+ @useAuth(BearerAuth)
240
+ create(@body body: ArticleInput): {
241
+ @statusCode _: 201;
242
+ @body body: Article;
243
+ } | BadRequest | Unauthorized;
244
+
245
+ @doc("Правка. Доступна только автору.")
246
+ @patch
247
+ @route("/{id}")
248
+ @useAuth(BearerAuth)
249
+ update(@path id: int32, @body body: ArticlePatch): Article
250
+ | BadRequest
251
+ | Unauthorized
252
+ | Forbidden
253
+ | NotFound;
254
+
255
+ @doc("Удаление вместе с комментариями и лайками. Доступно только автору.")
256
+ @delete
257
+ @route("/{id}")
258
+ @useAuth(BearerAuth)
259
+ remove(@path id: int32): {
260
+ @statusCode _: 204;
261
+ } | Unauthorized | Forbidden | NotFound;
262
+
263
+ @get
264
+ @route("/{id}/comments")
265
+ comments(@path id: int32): Comment[] | NotFound;
266
+
267
+ @post
268
+ @route("/{id}/comments")
269
+ @useAuth(BearerAuth)
270
+ comment(@path id: int32, @body body: CommentInput): {
271
+ @statusCode _: 201;
272
+ @body body: Comment;
273
+ } | BadRequest | Unauthorized | NotFound;
274
+
275
+ @doc("Поставить лайк. Повторный вызов ничего не меняет.")
276
+ @put
277
+ @route("/{id}/like")
278
+ @useAuth(BearerAuth)
279
+ like(@path id: int32): LikeState | Unauthorized | NotFound;
280
+
281
+ @doc("Снять лайк. Повторный вызов ничего не меняет.")
282
+ @delete
283
+ @route("/{id}/like")
284
+ @useAuth(BearerAuth)
285
+ unlike(@path id: int32): LikeState | Unauthorized | NotFound;
286
+ }