@evcraddock/slug-api 0.1.1 → 0.2.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.
@@ -0,0 +1,2019 @@
1
+ import { SLUGKIT_CONTRACT_ID, SLUGKIT_CONTRACT_VERSION } from "./contract.js";
2
+ const errorSchema = {
3
+ type: "object",
4
+ required: ["error"],
5
+ properties: {
6
+ error: {
7
+ type: "object",
8
+ required: ["code", "message", "operation"],
9
+ properties: {
10
+ code: {
11
+ type: "string",
12
+ enum: [
13
+ "AUTHENTICATION_ERROR",
14
+ "CONFLICT",
15
+ "NOT_FOUND",
16
+ "NOT_IMPLEMENTED",
17
+ "PAYLOAD_TOO_LARGE",
18
+ "STORAGE_ERROR",
19
+ "UNSUPPORTED_MEDIA_TYPE",
20
+ "VALIDATION_ERROR",
21
+ ],
22
+ },
23
+ message: { type: "string" },
24
+ operation: { type: "string" },
25
+ fields: {
26
+ type: "array",
27
+ items: {
28
+ type: "object",
29
+ required: ["field", "message"],
30
+ properties: {
31
+ field: { type: "string" },
32
+ message: { type: "string" },
33
+ },
34
+ },
35
+ },
36
+ },
37
+ },
38
+ },
39
+ };
40
+ const authenticationErrorResponse = {
41
+ description: "The API key is missing or invalid.",
42
+ content: {
43
+ "application/json": { schema: { $ref: "#/components/schemas/AuthenticationErrorResponse" } },
44
+ },
45
+ };
46
+ const validationErrorResponse = {
47
+ description: "The request is invalid.",
48
+ content: {
49
+ "application/json": { schema: { $ref: "#/components/schemas/ValidationErrorResponse" } },
50
+ },
51
+ };
52
+ const notFoundErrorResponse = {
53
+ description: "The requested resource was not found.",
54
+ content: { "application/json": { schema: { $ref: "#/components/schemas/NotFoundResponse" } } },
55
+ };
56
+ const notImplementedErrorResponse = {
57
+ description: "This site does not implement this operation.",
58
+ content: {
59
+ "application/json": { schema: { $ref: "#/components/schemas/NotImplementedResponse" } },
60
+ },
61
+ };
62
+ const conflictErrorResponse = {
63
+ description: "The request conflicts with an existing resource.",
64
+ content: { "application/json": { schema: { $ref: "#/components/schemas/ConflictResponse" } } },
65
+ };
66
+ const payloadTooLargeErrorResponse = {
67
+ description: "The uploaded media file is too large.",
68
+ content: {
69
+ "application/json": { schema: { $ref: "#/components/schemas/PayloadTooLargeResponse" } },
70
+ },
71
+ };
72
+ const unsupportedMediaTypeErrorResponse = {
73
+ description: "The uploaded media file type is not supported.",
74
+ content: {
75
+ "application/json": { schema: { $ref: "#/components/schemas/UnsupportedMediaTypeResponse" } },
76
+ },
77
+ };
78
+ const storageErrorResponse = {
79
+ description: "The media storage operation failed.",
80
+ content: {
81
+ "application/json": { schema: { $ref: "#/components/schemas/StorageErrorResponse" } },
82
+ },
83
+ };
84
+ export const openApiDocument = {
85
+ openapi: "3.1.0",
86
+ "x-slugkit-contract": { id: SLUGKIT_CONTRACT_ID, version: SLUGKIT_CONTRACT_VERSION },
87
+ info: {
88
+ title: "Slugkit API",
89
+ version: SLUGKIT_CONTRACT_VERSION,
90
+ },
91
+ servers: [{ url: "/api/v1" }],
92
+ paths: {
93
+ "/auth/check": {
94
+ get: {
95
+ operationId: "auth.check",
96
+ summary: "Check API key authentication",
97
+ security: [{ bearerAuth: [] }],
98
+ responses: {
99
+ "200": {
100
+ description: "The API key is valid.",
101
+ content: {
102
+ "application/json": {
103
+ schema: { $ref: "#/components/schemas/AuthCheckResponse" },
104
+ },
105
+ },
106
+ },
107
+ "401": {
108
+ description: "The API key is missing or invalid.",
109
+ content: {
110
+ "application/json": {
111
+ schema: { $ref: "#/components/schemas/AuthenticationErrorResponse" },
112
+ },
113
+ },
114
+ },
115
+ },
116
+ },
117
+ },
118
+ "/health": {
119
+ get: {
120
+ operationId: "health.get",
121
+ summary: "API health check",
122
+ responses: {
123
+ "200": {
124
+ description: "The API is reachable.",
125
+ content: {
126
+ "application/json": {
127
+ schema: { $ref: "#/components/schemas/HealthResponse" },
128
+ },
129
+ },
130
+ },
131
+ },
132
+ },
133
+ },
134
+ "/meta": {
135
+ get: {
136
+ operationId: "meta.get",
137
+ summary: "API metadata",
138
+ responses: {
139
+ "200": {
140
+ description: "Bootstrap metadata for Slugkit clients.",
141
+ content: {
142
+ "application/json": {
143
+ schema: { $ref: "#/components/schemas/MetaResponse" },
144
+ },
145
+ },
146
+ },
147
+ },
148
+ },
149
+ },
150
+ "/openapi.json": {
151
+ get: {
152
+ operationId: "openapi.get",
153
+ summary: "OpenAPI document",
154
+ responses: {
155
+ "200": {
156
+ description: "Slugkit OpenAPI 3.1 document.",
157
+ content: {
158
+ "application/json": {
159
+ schema: { type: "object" },
160
+ },
161
+ },
162
+ },
163
+ },
164
+ },
165
+ },
166
+ "/site-config": {
167
+ get: {
168
+ operationId: "siteConfig.get",
169
+ summary: "Get editable site configuration",
170
+ security: [{ bearerAuth: [] }],
171
+ responses: {
172
+ "200": {
173
+ description: "Current supported site configuration.",
174
+ content: {
175
+ "application/json": {
176
+ schema: { $ref: "#/components/schemas/SiteConfigResponse" },
177
+ },
178
+ },
179
+ },
180
+ "401": {
181
+ description: "The API key is missing or invalid.",
182
+ content: {
183
+ "application/json": {
184
+ schema: { $ref: "#/components/schemas/AuthenticationErrorResponse" },
185
+ },
186
+ },
187
+ },
188
+ },
189
+ },
190
+ patch: {
191
+ operationId: "siteConfig.update",
192
+ summary: "Update editable site configuration",
193
+ security: [{ bearerAuth: [] }],
194
+ requestBody: {
195
+ required: true,
196
+ content: {
197
+ "application/json": {
198
+ schema: { $ref: "#/components/schemas/SiteConfigUpdateRequest" },
199
+ },
200
+ },
201
+ },
202
+ responses: {
203
+ "200": {
204
+ description: "Updated supported site configuration.",
205
+ content: {
206
+ "application/json": {
207
+ schema: { $ref: "#/components/schemas/SiteConfigResponse" },
208
+ },
209
+ },
210
+ },
211
+ "401": {
212
+ description: "The API key is missing or invalid.",
213
+ content: {
214
+ "application/json": {
215
+ schema: { $ref: "#/components/schemas/AuthenticationErrorResponse" },
216
+ },
217
+ },
218
+ },
219
+ "422": {
220
+ description: "The requested config update is invalid.",
221
+ content: {
222
+ "application/json": {
223
+ schema: { $ref: "#/components/schemas/ValidationErrorResponse" },
224
+ },
225
+ },
226
+ },
227
+ },
228
+ },
229
+ },
230
+ "/posts": {
231
+ get: {
232
+ operationId: "posts.list",
233
+ summary: "List posts",
234
+ security: [{ bearerAuth: [] }],
235
+ parameters: [
236
+ {
237
+ name: "q",
238
+ in: "query",
239
+ required: false,
240
+ description: "Trimmed, case-insensitive literal substring of title, slug, content, excerpt, or destination URL. Filtering happens before pagination. Absent or blank queries retain existing list behavior; responses remain summaries without content.",
241
+ schema: { type: "string" },
242
+ },
243
+ {
244
+ name: "type",
245
+ in: "query",
246
+ required: false,
247
+ description: "All types when omitted.",
248
+ schema: { type: "string", enum: ["article", "link", "note"] },
249
+ },
250
+ {
251
+ name: "status",
252
+ in: "query",
253
+ required: false,
254
+ schema: { type: "string", enum: ["draft", "published", "all"], default: "published" },
255
+ },
256
+ {
257
+ name: "tag",
258
+ in: "query",
259
+ required: false,
260
+ description: "Tag slug; normalized using existing tag-filter semantics.",
261
+ schema: { type: "string" },
262
+ },
263
+ {
264
+ name: "limit",
265
+ in: "query",
266
+ required: false,
267
+ schema: { type: "integer", minimum: 1, maximum: 100, default: 50 },
268
+ },
269
+ {
270
+ name: "offset",
271
+ in: "query",
272
+ required: false,
273
+ schema: { type: "integer", minimum: 0, default: 0 },
274
+ },
275
+ ],
276
+ responses: {
277
+ "200": {
278
+ description: "Post list.",
279
+ content: {
280
+ "application/json": {
281
+ schema: { $ref: "#/components/schemas/PostListResponse" },
282
+ },
283
+ },
284
+ },
285
+ "401": authenticationErrorResponse,
286
+ "422": validationErrorResponse,
287
+ },
288
+ },
289
+ post: {
290
+ operationId: "posts.create",
291
+ summary: "Create a draft post",
292
+ security: [{ bearerAuth: [] }],
293
+ requestBody: {
294
+ required: true,
295
+ content: {
296
+ "application/json": {
297
+ schema: { $ref: "#/components/schemas/CreatePostRequest" },
298
+ },
299
+ },
300
+ },
301
+ responses: {
302
+ "201": {
303
+ description: "Created draft post.",
304
+ content: {
305
+ "application/json": {
306
+ schema: { $ref: "#/components/schemas/PostResponse" },
307
+ },
308
+ },
309
+ },
310
+ "401": authenticationErrorResponse,
311
+ "409": conflictErrorResponse,
312
+ "422": validationErrorResponse,
313
+ },
314
+ },
315
+ },
316
+ "/tags": {
317
+ get: {
318
+ operationId: "tags.list",
319
+ summary: "List tags",
320
+ security: [{ bearerAuth: [] }],
321
+ responses: {
322
+ "200": {
323
+ description: "Tag list.",
324
+ content: {
325
+ "application/json": {
326
+ schema: { $ref: "#/components/schemas/TagListResponse" },
327
+ },
328
+ },
329
+ },
330
+ "401": authenticationErrorResponse,
331
+ },
332
+ },
333
+ },
334
+ "/contacts": {
335
+ get: {
336
+ operationId: "contacts.list",
337
+ summary: "List contacts",
338
+ security: [{ bearerAuth: [] }],
339
+ parameters: [
340
+ {
341
+ name: "q",
342
+ in: "query",
343
+ required: false,
344
+ description: "Case-insensitive literal substring of a contact name or URL. Surrounding whitespace is trimmed; an absent or blank query returns all contacts in the existing order.",
345
+ schema: { type: "string" },
346
+ },
347
+ ],
348
+ responses: {
349
+ "200": {
350
+ description: "Contact list.",
351
+ content: {
352
+ "application/json": {
353
+ schema: { $ref: "#/components/schemas/ContactListResponse" },
354
+ },
355
+ },
356
+ },
357
+ "401": authenticationErrorResponse,
358
+ },
359
+ },
360
+ post: {
361
+ operationId: "contacts.create",
362
+ summary: "Create a contact",
363
+ security: [{ bearerAuth: [] }],
364
+ requestBody: {
365
+ required: true,
366
+ content: {
367
+ "application/json": {
368
+ schema: { $ref: "#/components/schemas/CreateContactRequest" },
369
+ },
370
+ },
371
+ },
372
+ responses: {
373
+ "201": {
374
+ description: "Created contact.",
375
+ content: {
376
+ "application/json": {
377
+ schema: { $ref: "#/components/schemas/ContactResponse" },
378
+ },
379
+ },
380
+ },
381
+ "401": authenticationErrorResponse,
382
+ "422": validationErrorResponse,
383
+ },
384
+ },
385
+ },
386
+ "/contacts/{id}": {
387
+ get: {
388
+ operationId: "contacts.get",
389
+ summary: "Get a contact by ID",
390
+ security: [{ bearerAuth: [] }],
391
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
392
+ responses: {
393
+ "200": {
394
+ description: "Contact details.",
395
+ content: {
396
+ "application/json": {
397
+ schema: { $ref: "#/components/schemas/ContactResponse" },
398
+ },
399
+ },
400
+ },
401
+ "401": authenticationErrorResponse,
402
+ "404": notFoundErrorResponse,
403
+ "422": validationErrorResponse,
404
+ },
405
+ },
406
+ put: {
407
+ operationId: "contacts.update",
408
+ summary: "Update a contact by ID",
409
+ security: [{ bearerAuth: [] }],
410
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
411
+ requestBody: {
412
+ required: true,
413
+ content: {
414
+ "application/json": {
415
+ schema: { $ref: "#/components/schemas/UpdateContactRequest" },
416
+ },
417
+ },
418
+ },
419
+ responses: {
420
+ "200": {
421
+ description: "Updated contact.",
422
+ content: {
423
+ "application/json": {
424
+ schema: { $ref: "#/components/schemas/ContactResponse" },
425
+ },
426
+ },
427
+ },
428
+ "401": authenticationErrorResponse,
429
+ "404": notFoundErrorResponse,
430
+ "422": validationErrorResponse,
431
+ },
432
+ },
433
+ delete: {
434
+ operationId: "contacts.delete",
435
+ summary: "Delete a contact by ID",
436
+ security: [{ bearerAuth: [] }],
437
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
438
+ responses: {
439
+ "204": { description: "Contact deleted." },
440
+ "401": authenticationErrorResponse,
441
+ "404": notFoundErrorResponse,
442
+ "409": conflictErrorResponse,
443
+ "422": validationErrorResponse,
444
+ },
445
+ },
446
+ },
447
+ "/sources": {
448
+ get: {
449
+ operationId: "sources.list",
450
+ summary: "List sources",
451
+ security: [{ bearerAuth: [] }],
452
+ parameters: [
453
+ {
454
+ name: "q",
455
+ in: "query",
456
+ required: false,
457
+ description: "Case-insensitive literal substring of a source name or URL. Surrounding whitespace is trimmed; an absent or blank query returns all sources in the existing order.",
458
+ schema: { type: "string" },
459
+ },
460
+ ],
461
+ responses: {
462
+ "200": {
463
+ description: "Source list.",
464
+ content: {
465
+ "application/json": {
466
+ schema: { $ref: "#/components/schemas/SourceListResponse" },
467
+ },
468
+ },
469
+ },
470
+ "401": authenticationErrorResponse,
471
+ },
472
+ },
473
+ post: {
474
+ operationId: "sources.create",
475
+ summary: "Create a source",
476
+ security: [{ bearerAuth: [] }],
477
+ requestBody: {
478
+ required: true,
479
+ content: {
480
+ "application/json": {
481
+ schema: { $ref: "#/components/schemas/CreateSourceRequest" },
482
+ },
483
+ },
484
+ },
485
+ responses: {
486
+ "201": {
487
+ description: "Created source.",
488
+ content: {
489
+ "application/json": {
490
+ schema: { $ref: "#/components/schemas/SourceResponse" },
491
+ },
492
+ },
493
+ },
494
+ "401": authenticationErrorResponse,
495
+ "422": validationErrorResponse,
496
+ },
497
+ },
498
+ },
499
+ "/sources/{id}": {
500
+ get: {
501
+ operationId: "sources.get",
502
+ summary: "Get a source by ID",
503
+ security: [{ bearerAuth: [] }],
504
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
505
+ responses: {
506
+ "200": {
507
+ description: "Source details.",
508
+ content: {
509
+ "application/json": {
510
+ schema: { $ref: "#/components/schemas/SourceResponse" },
511
+ },
512
+ },
513
+ },
514
+ "401": authenticationErrorResponse,
515
+ "404": notFoundErrorResponse,
516
+ "422": validationErrorResponse,
517
+ },
518
+ },
519
+ put: {
520
+ operationId: "sources.update",
521
+ summary: "Update a source by ID",
522
+ security: [{ bearerAuth: [] }],
523
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
524
+ requestBody: {
525
+ required: true,
526
+ content: {
527
+ "application/json": {
528
+ schema: { $ref: "#/components/schemas/UpdateSourceRequest" },
529
+ },
530
+ },
531
+ },
532
+ responses: {
533
+ "200": {
534
+ description: "Updated source.",
535
+ content: {
536
+ "application/json": {
537
+ schema: { $ref: "#/components/schemas/SourceResponse" },
538
+ },
539
+ },
540
+ },
541
+ "401": authenticationErrorResponse,
542
+ "404": notFoundErrorResponse,
543
+ "422": validationErrorResponse,
544
+ },
545
+ },
546
+ delete: {
547
+ operationId: "sources.delete",
548
+ summary: "Delete a source by ID",
549
+ security: [{ bearerAuth: [] }],
550
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
551
+ responses: {
552
+ "204": { description: "Source deleted." },
553
+ "401": authenticationErrorResponse,
554
+ "404": notFoundErrorResponse,
555
+ "409": conflictErrorResponse,
556
+ "422": validationErrorResponse,
557
+ },
558
+ },
559
+ },
560
+ "/accounts": {
561
+ get: {
562
+ operationId: "accounts.list",
563
+ summary: "List accounts",
564
+ security: [{ bearerAuth: [] }],
565
+ parameters: [
566
+ {
567
+ name: "q",
568
+ in: "query",
569
+ required: false,
570
+ description: "Case-insensitive literal substring of an account label or URL, combined with owner filters. Surrounding whitespace is trimmed; an absent or blank query preserves existing list behavior and ordering.",
571
+ schema: { type: "string" },
572
+ },
573
+ {
574
+ name: "ownerType",
575
+ in: "query",
576
+ required: false,
577
+ schema: { type: "string", enum: ["contact", "source", "site"] },
578
+ },
579
+ { name: "ownerId", in: "query", required: false, schema: { type: "integer" } },
580
+ ],
581
+ responses: {
582
+ "200": {
583
+ description: "Account list.",
584
+ content: {
585
+ "application/json": {
586
+ schema: { $ref: "#/components/schemas/AccountListResponse" },
587
+ },
588
+ },
589
+ },
590
+ "401": authenticationErrorResponse,
591
+ "422": validationErrorResponse,
592
+ },
593
+ },
594
+ post: {
595
+ operationId: "accounts.create",
596
+ summary: "Create an account",
597
+ security: [{ bearerAuth: [] }],
598
+ requestBody: {
599
+ required: true,
600
+ content: {
601
+ "application/json": {
602
+ schema: { $ref: "#/components/schemas/CreateAccountRequest" },
603
+ },
604
+ },
605
+ },
606
+ responses: {
607
+ "201": {
608
+ description: "Created account.",
609
+ content: {
610
+ "application/json": {
611
+ schema: { $ref: "#/components/schemas/AccountResponse" },
612
+ },
613
+ },
614
+ },
615
+ "401": authenticationErrorResponse,
616
+ "422": validationErrorResponse,
617
+ },
618
+ },
619
+ },
620
+ "/accounts/{id}": {
621
+ get: {
622
+ operationId: "accounts.get",
623
+ summary: "Get an account by ID",
624
+ security: [{ bearerAuth: [] }],
625
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
626
+ responses: {
627
+ "200": {
628
+ description: "Account details.",
629
+ content: {
630
+ "application/json": {
631
+ schema: { $ref: "#/components/schemas/AccountResponse" },
632
+ },
633
+ },
634
+ },
635
+ "401": authenticationErrorResponse,
636
+ "404": notFoundErrorResponse,
637
+ "422": validationErrorResponse,
638
+ },
639
+ },
640
+ put: {
641
+ operationId: "accounts.update",
642
+ summary: "Update an account by ID",
643
+ security: [{ bearerAuth: [] }],
644
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
645
+ requestBody: {
646
+ required: true,
647
+ content: {
648
+ "application/json": {
649
+ schema: { $ref: "#/components/schemas/UpdateAccountRequest" },
650
+ },
651
+ },
652
+ },
653
+ responses: {
654
+ "200": {
655
+ description: "Updated account.",
656
+ content: {
657
+ "application/json": {
658
+ schema: { $ref: "#/components/schemas/AccountResponse" },
659
+ },
660
+ },
661
+ },
662
+ "401": authenticationErrorResponse,
663
+ "404": notFoundErrorResponse,
664
+ "422": validationErrorResponse,
665
+ },
666
+ },
667
+ delete: {
668
+ operationId: "accounts.delete",
669
+ summary: "Delete an account by ID",
670
+ security: [{ bearerAuth: [] }],
671
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
672
+ responses: {
673
+ "204": { description: "Account deleted." },
674
+ "401": authenticationErrorResponse,
675
+ "404": notFoundErrorResponse,
676
+ "422": validationErrorResponse,
677
+ },
678
+ },
679
+ },
680
+ "/media": {
681
+ post: {
682
+ operationId: "media.upload",
683
+ summary: "Upload media",
684
+ security: [{ bearerAuth: [] }],
685
+ requestBody: {
686
+ required: true,
687
+ content: {
688
+ "multipart/form-data": {
689
+ schema: { $ref: "#/components/schemas/UploadMediaRequest" },
690
+ },
691
+ },
692
+ },
693
+ responses: {
694
+ "201": {
695
+ description: "Uploaded media metadata.",
696
+ content: {
697
+ "application/json": {
698
+ schema: { $ref: "#/components/schemas/MediaResponse" },
699
+ },
700
+ },
701
+ },
702
+ "400": validationErrorResponse,
703
+ "401": authenticationErrorResponse,
704
+ "413": payloadTooLargeErrorResponse,
705
+ "415": unsupportedMediaTypeErrorResponse,
706
+ "502": storageErrorResponse,
707
+ },
708
+ },
709
+ },
710
+ "/media/{id}": {
711
+ get: {
712
+ operationId: "media.get",
713
+ summary: "Get media metadata by ID",
714
+ security: [{ bearerAuth: [] }],
715
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
716
+ responses: {
717
+ "200": {
718
+ description: "Media metadata.",
719
+ content: {
720
+ "application/json": {
721
+ schema: { $ref: "#/components/schemas/MediaResponse" },
722
+ },
723
+ },
724
+ },
725
+ "400": validationErrorResponse,
726
+ "401": authenticationErrorResponse,
727
+ "404": notFoundErrorResponse,
728
+ },
729
+ },
730
+ delete: {
731
+ operationId: "media.delete",
732
+ summary: "Delete media by ID",
733
+ security: [{ bearerAuth: [] }],
734
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
735
+ responses: {
736
+ "204": { description: "Media deleted." },
737
+ "400": validationErrorResponse,
738
+ "401": authenticationErrorResponse,
739
+ "404": notFoundErrorResponse,
740
+ "502": storageErrorResponse,
741
+ },
742
+ },
743
+ },
744
+ "/followers": {
745
+ get: {
746
+ operationId: "followers.list",
747
+ summary: "List followers",
748
+ security: [{ bearerAuth: [] }],
749
+ responses: {
750
+ "200": {
751
+ description: "Follower list.",
752
+ content: {
753
+ "application/json": {
754
+ schema: { $ref: "#/components/schemas/FollowerListResponse" },
755
+ },
756
+ },
757
+ },
758
+ "401": authenticationErrorResponse,
759
+ "501": notImplementedErrorResponse,
760
+ },
761
+ },
762
+ },
763
+ "/following": {
764
+ get: {
765
+ operationId: "following.list",
766
+ summary: "List following records",
767
+ security: [{ bearerAuth: [] }],
768
+ parameters: [
769
+ {
770
+ name: "status",
771
+ in: "query",
772
+ required: false,
773
+ schema: {
774
+ type: "string",
775
+ enum: ["pending", "accepted", "rejected", "failed", "cancelled", "unfollowed"],
776
+ },
777
+ },
778
+ ],
779
+ responses: {
780
+ "200": {
781
+ description: "Following list.",
782
+ content: {
783
+ "application/json": {
784
+ schema: { $ref: "#/components/schemas/FollowingListResponse" },
785
+ },
786
+ },
787
+ },
788
+ "401": authenticationErrorResponse,
789
+ "422": validationErrorResponse,
790
+ "501": notImplementedErrorResponse,
791
+ },
792
+ },
793
+ post: {
794
+ operationId: "following.create",
795
+ summary: "Follow a target",
796
+ security: [{ bearerAuth: [] }],
797
+ requestBody: {
798
+ required: true,
799
+ content: {
800
+ "application/json": {
801
+ schema: { $ref: "#/components/schemas/FollowTargetRequest" },
802
+ },
803
+ },
804
+ },
805
+ responses: {
806
+ "201": {
807
+ description: "Created following record.",
808
+ content: {
809
+ "application/json": {
810
+ schema: { $ref: "#/components/schemas/FollowingResponse" },
811
+ },
812
+ },
813
+ },
814
+ "401": authenticationErrorResponse,
815
+ "409": conflictErrorResponse,
816
+ "422": validationErrorResponse,
817
+ "501": notImplementedErrorResponse,
818
+ },
819
+ },
820
+ },
821
+ "/following/{id}/unfollow": {
822
+ post: {
823
+ operationId: "following.unfollow",
824
+ summary: "Unfollow an accepted target or cancel a pending follow request",
825
+ security: [{ bearerAuth: [] }],
826
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
827
+ responses: {
828
+ "200": {
829
+ description: "Updated following status.",
830
+ content: {
831
+ "application/json": {
832
+ schema: { $ref: "#/components/schemas/FollowingStatusResponse" },
833
+ },
834
+ },
835
+ },
836
+ "401": authenticationErrorResponse,
837
+ "404": notFoundErrorResponse,
838
+ "409": conflictErrorResponse,
839
+ "422": validationErrorResponse,
840
+ "501": notImplementedErrorResponse,
841
+ },
842
+ },
843
+ },
844
+ "/posts/{slug}": {
845
+ get: {
846
+ operationId: "posts.get",
847
+ summary: "Get a post by slug",
848
+ security: [{ bearerAuth: [] }],
849
+ parameters: [{ name: "slug", in: "path", required: true, schema: { type: "string" } }],
850
+ responses: {
851
+ "200": {
852
+ description: "Post details.",
853
+ content: {
854
+ "application/json": {
855
+ schema: { $ref: "#/components/schemas/PostResponse" },
856
+ },
857
+ },
858
+ },
859
+ "401": authenticationErrorResponse,
860
+ "404": notFoundErrorResponse,
861
+ },
862
+ },
863
+ put: {
864
+ operationId: "posts.update",
865
+ summary: "Update a post by slug",
866
+ security: [{ bearerAuth: [] }],
867
+ parameters: [{ name: "slug", in: "path", required: true, schema: { type: "string" } }],
868
+ requestBody: {
869
+ required: true,
870
+ content: {
871
+ "application/json": {
872
+ schema: { $ref: "#/components/schemas/UpdatePostRequest" },
873
+ },
874
+ },
875
+ },
876
+ responses: {
877
+ "200": {
878
+ description: "Updated post.",
879
+ content: {
880
+ "application/json": {
881
+ schema: { $ref: "#/components/schemas/PostResponse" },
882
+ },
883
+ },
884
+ },
885
+ "401": authenticationErrorResponse,
886
+ "404": notFoundErrorResponse,
887
+ "409": conflictErrorResponse,
888
+ "422": validationErrorResponse,
889
+ },
890
+ },
891
+ delete: {
892
+ operationId: "posts.delete",
893
+ summary: "Delete a post by slug",
894
+ security: [{ bearerAuth: [] }],
895
+ parameters: [{ name: "slug", in: "path", required: true, schema: { type: "string" } }],
896
+ responses: {
897
+ "204": { description: "Post deleted." },
898
+ "401": authenticationErrorResponse,
899
+ "404": notFoundErrorResponse,
900
+ },
901
+ },
902
+ },
903
+ "/posts/{slug}/engagement": {
904
+ get: {
905
+ operationId: "posts.engagement.get",
906
+ summary: "Get post engagement summary",
907
+ security: [{ bearerAuth: [] }],
908
+ parameters: [{ name: "slug", in: "path", required: true, schema: { type: "string" } }],
909
+ responses: {
910
+ "200": {
911
+ description: "Post engagement summary.",
912
+ content: {
913
+ "application/json": {
914
+ schema: { $ref: "#/components/schemas/EngagementSummaryResponse" },
915
+ },
916
+ },
917
+ },
918
+ "401": authenticationErrorResponse,
919
+ "404": notFoundErrorResponse,
920
+ "501": notImplementedErrorResponse,
921
+ },
922
+ },
923
+ },
924
+ "/posts/{slug}/likes": {
925
+ get: {
926
+ operationId: "posts.likes.list",
927
+ summary: "List post likes",
928
+ security: [{ bearerAuth: [] }],
929
+ parameters: [{ name: "slug", in: "path", required: true, schema: { type: "string" } }],
930
+ responses: {
931
+ "200": {
932
+ description: "Post like actors.",
933
+ content: {
934
+ "application/json": {
935
+ schema: { $ref: "#/components/schemas/EngagementActorListResponse" },
936
+ },
937
+ },
938
+ },
939
+ "401": authenticationErrorResponse,
940
+ "404": notFoundErrorResponse,
941
+ "501": notImplementedErrorResponse,
942
+ },
943
+ },
944
+ },
945
+ "/posts/{slug}/boosts": {
946
+ get: {
947
+ operationId: "posts.boosts.list",
948
+ summary: "List post boosts",
949
+ security: [{ bearerAuth: [] }],
950
+ parameters: [{ name: "slug", in: "path", required: true, schema: { type: "string" } }],
951
+ responses: {
952
+ "200": {
953
+ description: "Post boost actors.",
954
+ content: {
955
+ "application/json": {
956
+ schema: { $ref: "#/components/schemas/EngagementActorListResponse" },
957
+ },
958
+ },
959
+ },
960
+ "401": authenticationErrorResponse,
961
+ "404": notFoundErrorResponse,
962
+ "501": notImplementedErrorResponse,
963
+ },
964
+ },
965
+ },
966
+ "/posts/{slug}/publish": {
967
+ post: {
968
+ operationId: "posts.publish",
969
+ summary: "Publish a draft post",
970
+ security: [{ bearerAuth: [] }],
971
+ parameters: [{ name: "slug", in: "path", required: true, schema: { type: "string" } }],
972
+ requestBody: {
973
+ required: false,
974
+ content: {
975
+ "application/json": { schema: { $ref: "#/components/schemas/PublishPostRequest" } },
976
+ },
977
+ },
978
+ responses: {
979
+ "200": {
980
+ description: "Published post.",
981
+ content: {
982
+ "application/json": { schema: { $ref: "#/components/schemas/PostResponse" } },
983
+ },
984
+ },
985
+ "401": authenticationErrorResponse,
986
+ "404": notFoundErrorResponse,
987
+ },
988
+ },
989
+ },
990
+ "/posts/{slug}/unpublish": {
991
+ post: {
992
+ operationId: "posts.unpublish",
993
+ summary: "Unpublish a post",
994
+ security: [{ bearerAuth: [] }],
995
+ parameters: [{ name: "slug", in: "path", required: true, schema: { type: "string" } }],
996
+ responses: {
997
+ "200": {
998
+ description: "Unpublished post.",
999
+ content: {
1000
+ "application/json": { schema: { $ref: "#/components/schemas/PostResponse" } },
1001
+ },
1002
+ },
1003
+ "401": authenticationErrorResponse,
1004
+ "404": notFoundErrorResponse,
1005
+ },
1006
+ },
1007
+ },
1008
+ "/posts/{slug}/comments": {
1009
+ get: {
1010
+ operationId: "posts.comments.list",
1011
+ summary: "List comments on a post",
1012
+ security: [{ bearerAuth: [] }],
1013
+ parameters: [
1014
+ { name: "slug", in: "path", required: true, schema: { type: "string" } },
1015
+ {
1016
+ name: "status",
1017
+ in: "query",
1018
+ required: false,
1019
+ schema: {
1020
+ type: "string",
1021
+ enum: ["pending", "approved", "hidden", "all"],
1022
+ default: "approved",
1023
+ },
1024
+ },
1025
+ ],
1026
+ responses: {
1027
+ "200": {
1028
+ description: "Post comment list.",
1029
+ content: {
1030
+ "application/json": {
1031
+ schema: { $ref: "#/components/schemas/CommentListResponse" },
1032
+ },
1033
+ },
1034
+ },
1035
+ "401": authenticationErrorResponse,
1036
+ "404": notFoundErrorResponse,
1037
+ "422": validationErrorResponse,
1038
+ "501": notImplementedErrorResponse,
1039
+ },
1040
+ },
1041
+ post: {
1042
+ operationId: "posts.comments.create",
1043
+ summary: "Create a comment on a post",
1044
+ security: [{ bearerAuth: [] }],
1045
+ parameters: [{ name: "slug", in: "path", required: true, schema: { type: "string" } }],
1046
+ requestBody: {
1047
+ required: true,
1048
+ content: {
1049
+ "application/json": {
1050
+ schema: { $ref: "#/components/schemas/CreatePostCommentRequest" },
1051
+ },
1052
+ },
1053
+ },
1054
+ responses: {
1055
+ "201": {
1056
+ description: "Created comment.",
1057
+ content: {
1058
+ "application/json": {
1059
+ schema: { $ref: "#/components/schemas/CommentResponse" },
1060
+ },
1061
+ },
1062
+ },
1063
+ "401": authenticationErrorResponse,
1064
+ "404": notFoundErrorResponse,
1065
+ "422": validationErrorResponse,
1066
+ "501": notImplementedErrorResponse,
1067
+ },
1068
+ },
1069
+ },
1070
+ "/comments": {
1071
+ get: {
1072
+ operationId: "comments.list",
1073
+ summary: "List comments across posts",
1074
+ security: [{ bearerAuth: [] }],
1075
+ parameters: [
1076
+ {
1077
+ name: "status",
1078
+ in: "query",
1079
+ required: false,
1080
+ schema: {
1081
+ type: "string",
1082
+ enum: ["pending", "approved", "hidden", "all"],
1083
+ default: "all",
1084
+ },
1085
+ },
1086
+ { name: "postSlug", in: "query", required: false, schema: { type: "string" } },
1087
+ { name: "author", in: "query", required: false, schema: { type: "string" } },
1088
+ {
1089
+ name: "receivedFrom",
1090
+ in: "query",
1091
+ required: false,
1092
+ schema: { type: "string", format: "date-time" },
1093
+ },
1094
+ {
1095
+ name: "receivedTo",
1096
+ in: "query",
1097
+ required: false,
1098
+ schema: { type: "string", format: "date-time" },
1099
+ },
1100
+ ],
1101
+ responses: {
1102
+ "200": {
1103
+ description: "Comment list.",
1104
+ content: {
1105
+ "application/json": {
1106
+ schema: { $ref: "#/components/schemas/CommentListResponse" },
1107
+ },
1108
+ },
1109
+ },
1110
+ "401": authenticationErrorResponse,
1111
+ "422": validationErrorResponse,
1112
+ "501": notImplementedErrorResponse,
1113
+ },
1114
+ },
1115
+ },
1116
+ "/comments/{id}/approve": {
1117
+ post: {
1118
+ operationId: "comments.approve",
1119
+ summary: "Approve a comment",
1120
+ security: [{ bearerAuth: [] }],
1121
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
1122
+ responses: {
1123
+ "200": {
1124
+ description: "Approved comment moderation state.",
1125
+ content: {
1126
+ "application/json": {
1127
+ schema: { $ref: "#/components/schemas/CommentModerationResponse" },
1128
+ },
1129
+ },
1130
+ },
1131
+ "401": authenticationErrorResponse,
1132
+ "404": notFoundErrorResponse,
1133
+ "422": validationErrorResponse,
1134
+ "501": notImplementedErrorResponse,
1135
+ },
1136
+ },
1137
+ },
1138
+ "/comments/{id}/hide": {
1139
+ post: {
1140
+ operationId: "comments.hide",
1141
+ summary: "Hide a comment",
1142
+ security: [{ bearerAuth: [] }],
1143
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
1144
+ responses: {
1145
+ "200": {
1146
+ description: "Hidden comment moderation state.",
1147
+ content: {
1148
+ "application/json": {
1149
+ schema: { $ref: "#/components/schemas/CommentModerationResponse" },
1150
+ },
1151
+ },
1152
+ },
1153
+ "401": authenticationErrorResponse,
1154
+ "404": notFoundErrorResponse,
1155
+ "422": validationErrorResponse,
1156
+ "501": notImplementedErrorResponse,
1157
+ },
1158
+ },
1159
+ },
1160
+ },
1161
+ components: {
1162
+ securitySchemes: {
1163
+ bearerAuth: {
1164
+ type: "http",
1165
+ scheme: "bearer",
1166
+ },
1167
+ },
1168
+ schemas: {
1169
+ AuthCheckResponse: {
1170
+ type: "object",
1171
+ required: ["data"],
1172
+ properties: {
1173
+ data: {
1174
+ type: "object",
1175
+ required: ["authenticated"],
1176
+ properties: {
1177
+ authenticated: { type: "boolean", const: true },
1178
+ },
1179
+ },
1180
+ },
1181
+ },
1182
+ HealthResponse: {
1183
+ type: "object",
1184
+ required: ["status", "service", "version", "time"],
1185
+ properties: {
1186
+ status: { type: "string", const: "ok" },
1187
+ service: { type: "string", const: "slugkit-api" },
1188
+ version: { type: "string" },
1189
+ time: { type: "string", format: "date-time" },
1190
+ },
1191
+ },
1192
+ MetaResponse: {
1193
+ type: "object",
1194
+ required: ["site", "api", "software"],
1195
+ properties: {
1196
+ site: {
1197
+ type: "object",
1198
+ required: ["name", "url"],
1199
+ properties: {
1200
+ name: { type: "string" },
1201
+ url: { type: "string", format: "uri" },
1202
+ },
1203
+ },
1204
+ api: {
1205
+ type: "object",
1206
+ required: ["name", "version", "baseUrl", "openapiUrl"],
1207
+ properties: {
1208
+ name: { type: "string", const: "slugkit" },
1209
+ version: { type: "string" },
1210
+ baseUrl: { type: "string", format: "uri" },
1211
+ openapiUrl: { type: "string", format: "uri" },
1212
+ contract: {
1213
+ type: "object",
1214
+ required: ["id", "version"],
1215
+ properties: {
1216
+ id: { type: "string", const: SLUGKIT_CONTRACT_ID },
1217
+ version: { type: "string", const: SLUGKIT_CONTRACT_VERSION },
1218
+ },
1219
+ },
1220
+ },
1221
+ },
1222
+ software: {
1223
+ type: "object",
1224
+ required: ["name", "version"],
1225
+ properties: {
1226
+ name: { type: "string", const: "slugkit-template" },
1227
+ version: { type: "string" },
1228
+ },
1229
+ },
1230
+ packageMetadata: {
1231
+ type: "object",
1232
+ required: ["packages", "advisoryOnly"],
1233
+ properties: {
1234
+ template: {
1235
+ type: "object",
1236
+ required: ["packageName", "name", "version"],
1237
+ properties: {
1238
+ packageName: { type: "string" },
1239
+ name: { type: "string" },
1240
+ version: { type: "string" },
1241
+ generatedAt: { type: "string", format: "date-time" },
1242
+ },
1243
+ },
1244
+ packages: {
1245
+ type: "object",
1246
+ additionalProperties: { type: "string" },
1247
+ },
1248
+ advisoryOnly: { type: "boolean", const: true },
1249
+ migrationNotesUrl: { type: "string", format: "uri" },
1250
+ },
1251
+ },
1252
+ },
1253
+ },
1254
+ JsonValue: {
1255
+ oneOf: [
1256
+ { type: "string" },
1257
+ { type: "number" },
1258
+ { type: "boolean" },
1259
+ { type: "null" },
1260
+ { type: "array", items: { $ref: "#/components/schemas/JsonValue" } },
1261
+ {
1262
+ type: "object",
1263
+ additionalProperties: { $ref: "#/components/schemas/JsonValue" },
1264
+ },
1265
+ ],
1266
+ },
1267
+ SiteConfigCore: {
1268
+ type: "object",
1269
+ required: ["name", "url", "tagline", "description", "homepage"],
1270
+ properties: {
1271
+ name: { type: "string" },
1272
+ url: { type: "string", format: "uri" },
1273
+ tagline: { type: "string" },
1274
+ description: { type: "string" },
1275
+ homepage: {
1276
+ type: "object",
1277
+ required: ["intro", "body"],
1278
+ properties: {
1279
+ intro: { type: "string" },
1280
+ body: { type: "string" },
1281
+ },
1282
+ },
1283
+ },
1284
+ },
1285
+ SiteConfig: {
1286
+ type: "object",
1287
+ required: ["core", "custom"],
1288
+ properties: {
1289
+ core: { $ref: "#/components/schemas/SiteConfigCore" },
1290
+ custom: {
1291
+ type: "object",
1292
+ additionalProperties: { $ref: "#/components/schemas/JsonValue" },
1293
+ },
1294
+ },
1295
+ },
1296
+ SiteConfigResponse: {
1297
+ type: "object",
1298
+ required: ["data"],
1299
+ properties: {
1300
+ data: { $ref: "#/components/schemas/SiteConfig" },
1301
+ },
1302
+ },
1303
+ SiteConfigUpdateRequest: {
1304
+ type: "object",
1305
+ minProperties: 1,
1306
+ additionalProperties: false,
1307
+ properties: {
1308
+ core: {
1309
+ type: "object",
1310
+ minProperties: 1,
1311
+ additionalProperties: false,
1312
+ properties: {
1313
+ name: { type: "string", minLength: 1 },
1314
+ url: { type: "string", format: "uri" },
1315
+ tagline: { type: "string", minLength: 1 },
1316
+ description: { type: "string", minLength: 1 },
1317
+ homepage: {
1318
+ type: "object",
1319
+ minProperties: 1,
1320
+ additionalProperties: false,
1321
+ properties: {
1322
+ intro: { type: "string", minLength: 1 },
1323
+ body: { type: "string", minLength: 1 },
1324
+ },
1325
+ },
1326
+ },
1327
+ },
1328
+ custom: {
1329
+ type: "object",
1330
+ additionalProperties: { $ref: "#/components/schemas/JsonValue" },
1331
+ },
1332
+ },
1333
+ },
1334
+ ContactSummary: {
1335
+ type: "object",
1336
+ required: ["id", "name", "url"],
1337
+ properties: {
1338
+ id: { type: "integer" },
1339
+ name: { type: "string" },
1340
+ url: { type: ["string", "null"], format: "uri" },
1341
+ },
1342
+ },
1343
+ Contact: {
1344
+ type: "object",
1345
+ required: ["id", "name", "url"],
1346
+ properties: {
1347
+ id: { type: "integer" },
1348
+ name: { type: "string" },
1349
+ url: { type: ["string", "null"], format: "uri" },
1350
+ },
1351
+ },
1352
+ ContactResponse: {
1353
+ type: "object",
1354
+ required: ["data"],
1355
+ properties: { data: { $ref: "#/components/schemas/Contact" } },
1356
+ },
1357
+ ContactListResponse: {
1358
+ type: "object",
1359
+ required: ["data"],
1360
+ properties: {
1361
+ data: { type: "array", items: { $ref: "#/components/schemas/Contact" } },
1362
+ },
1363
+ },
1364
+ CreateContactRequest: {
1365
+ type: "object",
1366
+ required: ["name"],
1367
+ additionalProperties: false,
1368
+ properties: {
1369
+ name: { type: "string", minLength: 1 },
1370
+ url: { type: ["string", "null"], format: "uri" },
1371
+ },
1372
+ },
1373
+ UpdateContactRequest: {
1374
+ type: "object",
1375
+ minProperties: 1,
1376
+ additionalProperties: false,
1377
+ properties: {
1378
+ name: { type: "string", minLength: 1 },
1379
+ url: { type: ["string", "null"], format: "uri" },
1380
+ },
1381
+ },
1382
+ AccountSummary: {
1383
+ type: "object",
1384
+ required: [
1385
+ "id",
1386
+ "ownerType",
1387
+ "ownerId",
1388
+ "label",
1389
+ "url",
1390
+ "kind",
1391
+ "protocol",
1392
+ "isDefault",
1393
+ "sortOrder",
1394
+ ],
1395
+ properties: {
1396
+ id: { type: "integer" },
1397
+ ownerType: { type: "string", enum: ["contact", "source", "site"] },
1398
+ ownerId: { type: ["integer", "null"] },
1399
+ label: { type: "string" },
1400
+ url: { type: "string", format: "uri" },
1401
+ kind: { type: ["string", "null"] },
1402
+ protocol: { type: ["string", "null"] },
1403
+ isDefault: { type: "boolean" },
1404
+ sortOrder: { type: "integer" },
1405
+ },
1406
+ },
1407
+ Account: {
1408
+ type: "object",
1409
+ required: [
1410
+ "id",
1411
+ "ownerType",
1412
+ "ownerId",
1413
+ "label",
1414
+ "url",
1415
+ "avatarUrl",
1416
+ "kind",
1417
+ "protocol",
1418
+ "isDefault",
1419
+ "sortOrder",
1420
+ ],
1421
+ properties: {
1422
+ id: { type: "integer" },
1423
+ ownerType: { type: "string", enum: ["contact", "source", "site"] },
1424
+ ownerId: { type: ["integer", "null"] },
1425
+ label: { type: "string" },
1426
+ url: { type: "string", format: "uri" },
1427
+ avatarUrl: { type: ["string", "null"], format: "uri" },
1428
+ kind: { type: ["string", "null"] },
1429
+ protocol: { type: ["string", "null"] },
1430
+ isDefault: { type: "boolean" },
1431
+ sortOrder: { type: "integer" },
1432
+ },
1433
+ },
1434
+ AccountResponse: {
1435
+ type: "object",
1436
+ required: ["data"],
1437
+ properties: { data: { $ref: "#/components/schemas/Account" } },
1438
+ },
1439
+ AccountListResponse: {
1440
+ type: "object",
1441
+ required: ["data"],
1442
+ properties: { data: { type: "array", items: { $ref: "#/components/schemas/Account" } } },
1443
+ },
1444
+ CreateAccountRequest: {
1445
+ type: "object",
1446
+ required: ["ownerType", "label", "url"],
1447
+ additionalProperties: false,
1448
+ properties: {
1449
+ ownerType: { type: "string", enum: ["contact", "source", "site"] },
1450
+ ownerId: { type: "integer", minimum: 1 },
1451
+ label: { type: "string", minLength: 1 },
1452
+ url: { type: "string", format: "uri" },
1453
+ avatarUrl: { type: ["string", "null"], format: "uri" },
1454
+ kind: { type: ["string", "null"] },
1455
+ protocol: { type: ["string", "null"] },
1456
+ isDefault: { type: "boolean" },
1457
+ sortOrder: { type: "integer" },
1458
+ },
1459
+ },
1460
+ UpdateAccountRequest: {
1461
+ type: "object",
1462
+ minProperties: 1,
1463
+ additionalProperties: false,
1464
+ properties: {
1465
+ label: { type: "string", minLength: 1 },
1466
+ url: { type: "string", format: "uri" },
1467
+ avatarUrl: { type: ["string", "null"], format: "uri" },
1468
+ kind: { type: ["string", "null"] },
1469
+ protocol: { type: ["string", "null"] },
1470
+ isDefault: { type: "boolean" },
1471
+ sortOrder: { type: "integer" },
1472
+ },
1473
+ },
1474
+ Source: {
1475
+ type: "object",
1476
+ required: [
1477
+ "id",
1478
+ "name",
1479
+ "url",
1480
+ "description",
1481
+ "imageUrl",
1482
+ "faviconUrl",
1483
+ "contacts",
1484
+ "accounts",
1485
+ ],
1486
+ properties: {
1487
+ id: { type: "integer" },
1488
+ name: { type: "string" },
1489
+ url: { type: ["string", "null"], format: "uri" },
1490
+ description: { type: ["string", "null"] },
1491
+ imageUrl: { type: ["string", "null"], format: "uri" },
1492
+ faviconUrl: { type: ["string", "null"], format: "uri" },
1493
+ contacts: { type: "array", items: { $ref: "#/components/schemas/ContactSummary" } },
1494
+ accounts: { type: "array", items: { $ref: "#/components/schemas/AccountSummary" } },
1495
+ },
1496
+ },
1497
+ SourceResponse: {
1498
+ type: "object",
1499
+ required: ["data"],
1500
+ properties: { data: { $ref: "#/components/schemas/Source" } },
1501
+ },
1502
+ SourceListResponse: {
1503
+ type: "object",
1504
+ required: ["data"],
1505
+ properties: {
1506
+ data: { type: "array", items: { $ref: "#/components/schemas/Source" } },
1507
+ },
1508
+ },
1509
+ CreateSourceRequest: {
1510
+ type: "object",
1511
+ required: ["name"],
1512
+ additionalProperties: false,
1513
+ properties: {
1514
+ name: { type: "string", minLength: 1 },
1515
+ url: { type: ["string", "null"], format: "uri" },
1516
+ description: { type: ["string", "null"] },
1517
+ imageUrl: { type: ["string", "null"], format: "uri" },
1518
+ faviconUrl: { type: ["string", "null"], format: "uri" },
1519
+ contactIds: { type: "array", items: { type: "integer", minimum: 1 } },
1520
+ },
1521
+ },
1522
+ UpdateSourceRequest: {
1523
+ type: "object",
1524
+ minProperties: 1,
1525
+ additionalProperties: false,
1526
+ properties: {
1527
+ name: { type: "string", minLength: 1 },
1528
+ url: { type: ["string", "null"], format: "uri" },
1529
+ description: { type: ["string", "null"] },
1530
+ imageUrl: { type: ["string", "null"], format: "uri" },
1531
+ faviconUrl: { type: ["string", "null"], format: "uri" },
1532
+ contactIds: { type: "array", items: { type: "integer", minimum: 1 } },
1533
+ },
1534
+ },
1535
+ TagSummary: {
1536
+ type: "object",
1537
+ required: ["id", "name", "slug"],
1538
+ properties: {
1539
+ id: { type: "integer" },
1540
+ name: { type: "string" },
1541
+ slug: { type: "string" },
1542
+ },
1543
+ },
1544
+ Tag: {
1545
+ type: "object",
1546
+ required: ["id", "name", "slug", "count"],
1547
+ properties: {
1548
+ id: { type: "integer" },
1549
+ name: { type: "string" },
1550
+ slug: { type: "string" },
1551
+ count: { type: "integer" },
1552
+ },
1553
+ },
1554
+ TagListResponse: {
1555
+ type: "object",
1556
+ required: ["data"],
1557
+ properties: {
1558
+ data: { type: "array", items: { $ref: "#/components/schemas/Tag" } },
1559
+ },
1560
+ },
1561
+ Follower: {
1562
+ type: "object",
1563
+ required: ["id", "profileUrl", "displayName", "handle", "inboxUrl", "followedAt"],
1564
+ properties: {
1565
+ id: { type: "integer" },
1566
+ profileUrl: { type: "string", format: "uri" },
1567
+ displayName: { type: "string" },
1568
+ handle: { type: "string" },
1569
+ inboxUrl: { type: "string", format: "uri" },
1570
+ followedAt: { type: "string", format: "date-time" },
1571
+ },
1572
+ },
1573
+ FollowerListResponse: {
1574
+ type: "object",
1575
+ required: ["data"],
1576
+ properties: { data: { type: "array", items: { $ref: "#/components/schemas/Follower" } } },
1577
+ },
1578
+ Following: {
1579
+ type: "object",
1580
+ required: [
1581
+ "id",
1582
+ "contactId",
1583
+ "profileUrl",
1584
+ "displayName",
1585
+ "handle",
1586
+ "inboxUrl",
1587
+ "avatarUrl",
1588
+ "status",
1589
+ "lastError",
1590
+ "followedAt",
1591
+ "acceptedAt",
1592
+ "rejectedAt",
1593
+ "unfollowedAt",
1594
+ ],
1595
+ properties: {
1596
+ id: { type: "integer" },
1597
+ contactId: { type: "integer" },
1598
+ profileUrl: { type: "string", format: "uri" },
1599
+ displayName: { type: "string" },
1600
+ handle: { type: "string" },
1601
+ inboxUrl: { type: "string", format: "uri" },
1602
+ avatarUrl: { type: ["string", "null"], format: "uri" },
1603
+ status: {
1604
+ type: "string",
1605
+ enum: ["pending", "accepted", "rejected", "failed", "cancelled", "unfollowed"],
1606
+ },
1607
+ lastError: { type: ["string", "null"] },
1608
+ followedAt: { type: "string", format: "date-time" },
1609
+ acceptedAt: { type: ["string", "null"], format: "date-time" },
1610
+ rejectedAt: { type: ["string", "null"], format: "date-time" },
1611
+ unfollowedAt: { type: ["string", "null"], format: "date-time" },
1612
+ },
1613
+ },
1614
+ FollowingResponse: {
1615
+ type: "object",
1616
+ required: ["data"],
1617
+ properties: { data: { $ref: "#/components/schemas/Following" } },
1618
+ },
1619
+ FollowingListResponse: {
1620
+ type: "object",
1621
+ required: ["data"],
1622
+ properties: { data: { type: "array", items: { $ref: "#/components/schemas/Following" } } },
1623
+ },
1624
+ FollowTargetRequest: {
1625
+ type: "object",
1626
+ required: ["target"],
1627
+ additionalProperties: false,
1628
+ properties: { target: { type: "string", minLength: 1 } },
1629
+ },
1630
+ FollowingStatus: {
1631
+ type: "object",
1632
+ required: ["id", "status", "unfollowedAt"],
1633
+ properties: {
1634
+ id: { type: "integer" },
1635
+ status: { type: "string", enum: ["cancelled", "unfollowed"] },
1636
+ unfollowedAt: { type: ["string", "null"], format: "date-time" },
1637
+ },
1638
+ },
1639
+ FollowingStatusResponse: {
1640
+ type: "object",
1641
+ required: ["data"],
1642
+ properties: { data: { $ref: "#/components/schemas/FollowingStatus" } },
1643
+ },
1644
+ EngagementSummary: {
1645
+ type: "object",
1646
+ required: ["postSlug", "likes", "boosts", "comments"],
1647
+ properties: {
1648
+ postSlug: { type: "string" },
1649
+ likes: {
1650
+ type: "object",
1651
+ required: ["count"],
1652
+ properties: { count: { type: "integer" } },
1653
+ },
1654
+ boosts: {
1655
+ type: "object",
1656
+ required: ["count"],
1657
+ properties: { count: { type: "integer" } },
1658
+ },
1659
+ comments: {
1660
+ type: "object",
1661
+ required: ["count", "pendingCount"],
1662
+ properties: { count: { type: "integer" }, pendingCount: { type: "integer" } },
1663
+ },
1664
+ },
1665
+ },
1666
+ EngagementSummaryResponse: {
1667
+ type: "object",
1668
+ required: ["data"],
1669
+ properties: { data: { $ref: "#/components/schemas/EngagementSummary" } },
1670
+ },
1671
+ EngagementActor: {
1672
+ type: "object",
1673
+ required: ["profileUrl", "displayName", "handle", "activityUrl", "objectUrl", "receivedAt"],
1674
+ properties: {
1675
+ profileUrl: { type: "string", format: "uri" },
1676
+ displayName: { type: "string" },
1677
+ handle: { type: "string" },
1678
+ activityUrl: { type: "string", format: "uri" },
1679
+ objectUrl: { type: "string", format: "uri" },
1680
+ receivedAt: { type: "string", format: "date-time" },
1681
+ },
1682
+ },
1683
+ EngagementActorListResponse: {
1684
+ type: "object",
1685
+ required: ["data"],
1686
+ properties: {
1687
+ data: { type: "array", items: { $ref: "#/components/schemas/EngagementActor" } },
1688
+ },
1689
+ },
1690
+ Media: {
1691
+ type: "object",
1692
+ required: ["id", "filename", "mimeType", "key", "altText", "url", "createdAt"],
1693
+ properties: {
1694
+ id: { type: "integer" },
1695
+ filename: { type: "string" },
1696
+ mimeType: { type: "string" },
1697
+ key: { type: "string" },
1698
+ altText: { type: ["string", "null"] },
1699
+ url: { type: "string", format: "uri" },
1700
+ createdAt: { type: "string", format: "date-time" },
1701
+ },
1702
+ },
1703
+ MediaResponse: {
1704
+ type: "object",
1705
+ required: ["data"],
1706
+ properties: { data: { $ref: "#/components/schemas/Media" } },
1707
+ },
1708
+ UploadMediaRequest: {
1709
+ type: "object",
1710
+ required: ["file"],
1711
+ properties: {
1712
+ file: { type: "string", format: "binary" },
1713
+ altText: { type: "string" },
1714
+ key: { type: "string" },
1715
+ },
1716
+ },
1717
+ Post: {
1718
+ type: "object",
1719
+ required: [
1720
+ "id",
1721
+ "slug",
1722
+ "type",
1723
+ "title",
1724
+ "content",
1725
+ "excerpt",
1726
+ "url",
1727
+ "bannerUrl",
1728
+ "sourceId",
1729
+ "source",
1730
+ "creditContactIds",
1731
+ "creditedContacts",
1732
+ "tags",
1733
+ "publishedAt",
1734
+ "createdAt",
1735
+ "updatedAt",
1736
+ ],
1737
+ properties: {
1738
+ id: { type: "integer" },
1739
+ slug: { type: "string" },
1740
+ type: { type: "string", enum: ["article", "link", "note"] },
1741
+ title: { type: ["string", "null"] },
1742
+ content: { type: "string" },
1743
+ excerpt: { type: ["string", "null"] },
1744
+ url: { type: ["string", "null"], format: "uri" },
1745
+ bannerUrl: { type: ["string", "null"], format: "uri" },
1746
+ sourceId: { type: ["integer", "null"] },
1747
+ source: {
1748
+ oneOf: [{ $ref: "#/components/schemas/Source" }, { type: "null" }],
1749
+ },
1750
+ creditContactIds: {
1751
+ type: "array",
1752
+ description: "Contact IDs credited for external, source, or linked-content context. These are not local post authors.",
1753
+ items: { type: "integer" },
1754
+ },
1755
+ creditedContacts: {
1756
+ type: "array",
1757
+ description: "Contacts credited for external, source, or linked-content context. These are not local post authors.",
1758
+ items: { $ref: "#/components/schemas/ContactSummary" },
1759
+ },
1760
+ tags: { type: "array", items: { $ref: "#/components/schemas/TagSummary" } },
1761
+ publishedAt: { type: ["string", "null"], format: "date-time" },
1762
+ createdAt: { type: "string", format: "date-time" },
1763
+ updatedAt: { type: "string", format: "date-time" },
1764
+ },
1765
+ },
1766
+ PostListItem: {
1767
+ type: "object",
1768
+ required: [
1769
+ "id",
1770
+ "slug",
1771
+ "type",
1772
+ "title",
1773
+ "excerpt",
1774
+ "url",
1775
+ "bannerUrl",
1776
+ "sourceId",
1777
+ "source",
1778
+ "creditContactIds",
1779
+ "creditedContacts",
1780
+ "tags",
1781
+ "publishedAt",
1782
+ "createdAt",
1783
+ "updatedAt",
1784
+ ],
1785
+ properties: {
1786
+ id: { type: "integer" },
1787
+ slug: { type: "string" },
1788
+ type: { type: "string", enum: ["article", "link", "note"] },
1789
+ title: { type: ["string", "null"] },
1790
+ excerpt: { type: ["string", "null"] },
1791
+ url: { type: ["string", "null"], format: "uri" },
1792
+ bannerUrl: { type: ["string", "null"], format: "uri" },
1793
+ sourceId: { type: ["integer", "null"] },
1794
+ source: {
1795
+ oneOf: [{ $ref: "#/components/schemas/Source" }, { type: "null" }],
1796
+ },
1797
+ creditContactIds: {
1798
+ type: "array",
1799
+ description: "Contact IDs credited for external, source, or linked-content context. These are not local post authors.",
1800
+ items: { type: "integer" },
1801
+ },
1802
+ creditedContacts: {
1803
+ type: "array",
1804
+ description: "Contacts credited for external, source, or linked-content context. These are not local post authors.",
1805
+ items: { $ref: "#/components/schemas/ContactSummary" },
1806
+ },
1807
+ tags: { type: "array", items: { $ref: "#/components/schemas/TagSummary" } },
1808
+ publishedAt: { type: ["string", "null"], format: "date-time" },
1809
+ createdAt: { type: "string", format: "date-time" },
1810
+ updatedAt: { type: "string", format: "date-time" },
1811
+ },
1812
+ },
1813
+ PostResponse: {
1814
+ type: "object",
1815
+ required: ["data"],
1816
+ properties: { data: { $ref: "#/components/schemas/Post" } },
1817
+ },
1818
+ PostListResponse: {
1819
+ type: "object",
1820
+ required: ["data", "meta"],
1821
+ properties: {
1822
+ data: { type: "array", items: { $ref: "#/components/schemas/PostListItem" } },
1823
+ meta: {
1824
+ type: "object",
1825
+ required: ["limit", "offset"],
1826
+ properties: { limit: { type: "integer" }, offset: { type: "integer" } },
1827
+ },
1828
+ },
1829
+ },
1830
+ Comment: {
1831
+ type: "object",
1832
+ required: [
1833
+ "id",
1834
+ "postSlug",
1835
+ "activityUrl",
1836
+ "objectUrl",
1837
+ "authorProfileUrl",
1838
+ "authorName",
1839
+ "authorHandle",
1840
+ "contentHtml",
1841
+ "contentText",
1842
+ "inReplyToUrl",
1843
+ "moderationStatus",
1844
+ "publishedAt",
1845
+ "receivedAt",
1846
+ "moderatedAt",
1847
+ ],
1848
+ properties: {
1849
+ id: { type: "integer" },
1850
+ postSlug: { type: "string" },
1851
+ activityUrl: { type: "string", format: "uri" },
1852
+ objectUrl: { type: "string", format: "uri" },
1853
+ authorProfileUrl: { type: "string", format: "uri" },
1854
+ authorName: { type: "string" },
1855
+ authorHandle: { type: "string" },
1856
+ contentHtml: { type: "string" },
1857
+ contentText: { type: "string" },
1858
+ inReplyToUrl: { type: "string", format: "uri" },
1859
+ moderationStatus: { type: "string", enum: ["pending", "approved", "hidden"] },
1860
+ publishedAt: { type: "string", format: "date-time" },
1861
+ receivedAt: { type: "string", format: "date-time" },
1862
+ moderatedAt: { type: ["string", "null"], format: "date-time" },
1863
+ },
1864
+ },
1865
+ CommentListItem: {
1866
+ type: "object",
1867
+ required: [
1868
+ "id",
1869
+ "postSlug",
1870
+ "authorProfileUrl",
1871
+ "authorName",
1872
+ "authorHandle",
1873
+ "contentText",
1874
+ "moderationStatus",
1875
+ "receivedAt",
1876
+ ],
1877
+ properties: {
1878
+ id: { type: "integer" },
1879
+ postSlug: { type: "string" },
1880
+ authorProfileUrl: { type: "string", format: "uri" },
1881
+ authorName: { type: "string" },
1882
+ authorHandle: { type: "string" },
1883
+ contentText: { type: "string" },
1884
+ moderationStatus: { type: "string", enum: ["pending", "approved", "hidden"] },
1885
+ receivedAt: { type: "string", format: "date-time" },
1886
+ },
1887
+ },
1888
+ CommentListResponse: {
1889
+ type: "object",
1890
+ required: ["data"],
1891
+ properties: {
1892
+ data: { type: "array", items: { $ref: "#/components/schemas/CommentListItem" } },
1893
+ },
1894
+ },
1895
+ CommentResponse: {
1896
+ type: "object",
1897
+ required: ["data"],
1898
+ properties: { data: { $ref: "#/components/schemas/Comment" } },
1899
+ },
1900
+ CreatePostCommentRequest: {
1901
+ type: "object",
1902
+ required: ["content"],
1903
+ additionalProperties: false,
1904
+ properties: { content: { type: "string", minLength: 1 } },
1905
+ },
1906
+ CommentModeration: {
1907
+ type: "object",
1908
+ required: ["id", "moderationStatus", "moderatedAt"],
1909
+ properties: {
1910
+ id: { type: "integer" },
1911
+ moderationStatus: { type: "string", enum: ["approved", "hidden"] },
1912
+ moderatedAt: { type: "string", format: "date-time" },
1913
+ },
1914
+ },
1915
+ CommentModerationResponse: {
1916
+ type: "object",
1917
+ required: ["data"],
1918
+ properties: { data: { $ref: "#/components/schemas/CommentModeration" } },
1919
+ },
1920
+ CreatePostRequest: {
1921
+ type: "object",
1922
+ required: ["type", "slug", "content"],
1923
+ properties: {
1924
+ type: { type: "string", enum: ["article", "link", "note"] },
1925
+ slug: { type: "string" },
1926
+ title: { type: ["string", "null"] },
1927
+ content: { type: "string" },
1928
+ excerpt: { type: ["string", "null"] },
1929
+ url: { type: ["string", "null"], format: "uri" },
1930
+ bannerUrl: { type: ["string", "null"], format: "uri" },
1931
+ sourceId: { type: ["integer", "null"] },
1932
+ creditContactIds: {
1933
+ type: "array",
1934
+ description: "Contact IDs credited for external, source, or linked-content context. These are not local post authors.",
1935
+ items: { type: "integer" },
1936
+ },
1937
+ tagSlugs: { type: "array", items: { type: "string" } },
1938
+ publishedAt: {
1939
+ type: ["string", "null"],
1940
+ format: "date-time",
1941
+ description: "Optional original publish timestamp for migration/import workflows. When supplied on create, the post is created as already published without ActivityPub follower delivery.",
1942
+ },
1943
+ },
1944
+ },
1945
+ UpdatePostRequest: {
1946
+ type: "object",
1947
+ minProperties: 1,
1948
+ properties: {
1949
+ slug: { type: "string" },
1950
+ title: { type: ["string", "null"] },
1951
+ content: { type: "string" },
1952
+ excerpt: { type: ["string", "null"] },
1953
+ url: { type: ["string", "null"], format: "uri" },
1954
+ bannerUrl: { type: ["string", "null"], format: "uri" },
1955
+ sourceId: { type: ["integer", "null"] },
1956
+ creditContactIds: {
1957
+ type: "array",
1958
+ description: "Contact IDs credited for external, source, or linked-content context. These are not local post authors.",
1959
+ items: { type: "integer" },
1960
+ },
1961
+ tagSlugs: { type: "array", items: { type: "string" } },
1962
+ publishedAt: {
1963
+ type: ["string", "null"],
1964
+ format: "date-time",
1965
+ description: "Optional explicit publish timestamp for migration/import corrections.",
1966
+ },
1967
+ },
1968
+ },
1969
+ PublishPostRequest: {
1970
+ type: "object",
1971
+ properties: {
1972
+ publishedAt: {
1973
+ type: ["string", "null"],
1974
+ format: "date-time",
1975
+ description: "Optional explicit publish timestamp. When omitted, publishing uses the current server time and normal follower delivery behavior.",
1976
+ },
1977
+ },
1978
+ },
1979
+ SuccessResponse: {
1980
+ type: "object",
1981
+ required: ["data"],
1982
+ properties: {
1983
+ data: true,
1984
+ },
1985
+ },
1986
+ FieldError: {
1987
+ type: "object",
1988
+ required: ["field", "message"],
1989
+ properties: {
1990
+ field: { type: "string" },
1991
+ message: { type: "string" },
1992
+ },
1993
+ },
1994
+ ErrorResponse: errorSchema,
1995
+ ValidationErrorResponse: errorSchema,
1996
+ NotFoundResponse: errorSchema,
1997
+ ConflictResponse: errorSchema,
1998
+ AuthenticationErrorResponse: errorSchema,
1999
+ PayloadTooLargeResponse: errorSchema,
2000
+ StorageErrorResponse: errorSchema,
2001
+ UnsupportedMediaTypeResponse: errorSchema,
2002
+ NotImplementedResponse: {
2003
+ type: "object",
2004
+ required: ["error"],
2005
+ properties: {
2006
+ error: {
2007
+ type: "object",
2008
+ required: ["code", "message", "operation"],
2009
+ properties: {
2010
+ code: { type: "string", const: "NOT_IMPLEMENTED" },
2011
+ message: { type: "string", const: "This site does not implement this operation." },
2012
+ operation: { type: "string" },
2013
+ },
2014
+ },
2015
+ },
2016
+ },
2017
+ },
2018
+ },
2019
+ };