@evcraddock/slug-api 0.1.1 → 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.
@@ -0,0 +1,2327 @@
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
+ description: "Changing the URL of an account referenced by following returns 409; other metadata remains editable.",
644
+ security: [{ bearerAuth: [] }],
645
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
646
+ requestBody: {
647
+ required: true,
648
+ content: {
649
+ "application/json": {
650
+ schema: { $ref: "#/components/schemas/UpdateAccountRequest" },
651
+ },
652
+ },
653
+ },
654
+ responses: {
655
+ "200": {
656
+ description: "Updated account.",
657
+ content: {
658
+ "application/json": {
659
+ schema: { $ref: "#/components/schemas/AccountResponse" },
660
+ },
661
+ },
662
+ },
663
+ "401": authenticationErrorResponse,
664
+ "404": notFoundErrorResponse,
665
+ "409": conflictErrorResponse,
666
+ "422": validationErrorResponse,
667
+ },
668
+ },
669
+ delete: {
670
+ operationId: "accounts.delete",
671
+ summary: "Delete an account by ID",
672
+ description: "Accounts referenced by following (including inactive records) cannot be deleted; returns 409.",
673
+ security: [{ bearerAuth: [] }],
674
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
675
+ responses: {
676
+ "204": { description: "Account deleted." },
677
+ "401": authenticationErrorResponse,
678
+ "404": notFoundErrorResponse,
679
+ "409": conflictErrorResponse,
680
+ "422": validationErrorResponse,
681
+ },
682
+ },
683
+ },
684
+ "/media": {
685
+ post: {
686
+ operationId: "media.upload",
687
+ summary: "Upload media",
688
+ security: [{ bearerAuth: [] }],
689
+ requestBody: {
690
+ required: true,
691
+ content: {
692
+ "multipart/form-data": {
693
+ schema: { $ref: "#/components/schemas/UploadMediaRequest" },
694
+ },
695
+ },
696
+ },
697
+ responses: {
698
+ "201": {
699
+ description: "Uploaded media metadata.",
700
+ content: {
701
+ "application/json": {
702
+ schema: { $ref: "#/components/schemas/MediaResponse" },
703
+ },
704
+ },
705
+ },
706
+ "400": validationErrorResponse,
707
+ "401": authenticationErrorResponse,
708
+ "413": payloadTooLargeErrorResponse,
709
+ "415": unsupportedMediaTypeErrorResponse,
710
+ "502": storageErrorResponse,
711
+ },
712
+ },
713
+ },
714
+ "/media/{id}": {
715
+ get: {
716
+ operationId: "media.get",
717
+ summary: "Get media metadata by ID",
718
+ security: [{ bearerAuth: [] }],
719
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
720
+ responses: {
721
+ "200": {
722
+ description: "Media metadata.",
723
+ content: {
724
+ "application/json": {
725
+ schema: { $ref: "#/components/schemas/MediaResponse" },
726
+ },
727
+ },
728
+ },
729
+ "400": validationErrorResponse,
730
+ "401": authenticationErrorResponse,
731
+ "404": notFoundErrorResponse,
732
+ },
733
+ },
734
+ delete: {
735
+ operationId: "media.delete",
736
+ summary: "Delete media by ID",
737
+ security: [{ bearerAuth: [] }],
738
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
739
+ responses: {
740
+ "204": { description: "Media deleted." },
741
+ "400": validationErrorResponse,
742
+ "401": authenticationErrorResponse,
743
+ "404": notFoundErrorResponse,
744
+ "502": storageErrorResponse,
745
+ },
746
+ },
747
+ },
748
+ "/followers": {
749
+ get: {
750
+ operationId: "followers.list",
751
+ summary: "List followers",
752
+ security: [{ bearerAuth: [] }],
753
+ responses: {
754
+ "200": {
755
+ description: "Follower list.",
756
+ content: {
757
+ "application/json": {
758
+ schema: { $ref: "#/components/schemas/FollowerListResponse" },
759
+ },
760
+ },
761
+ },
762
+ "401": authenticationErrorResponse,
763
+ "501": notImplementedErrorResponse,
764
+ },
765
+ },
766
+ },
767
+ "/following": {
768
+ get: {
769
+ operationId: "following.list",
770
+ summary: "List following records",
771
+ security: [{ bearerAuth: [] }],
772
+ parameters: [
773
+ {
774
+ name: "status",
775
+ in: "query",
776
+ required: false,
777
+ schema: {
778
+ type: "string",
779
+ enum: ["pending", "accepted", "rejected", "failed", "cancelled", "unfollowed"],
780
+ },
781
+ },
782
+ ],
783
+ responses: {
784
+ "200": {
785
+ description: "Following list.",
786
+ content: {
787
+ "application/json": {
788
+ schema: { $ref: "#/components/schemas/FollowingListResponse" },
789
+ },
790
+ },
791
+ },
792
+ "401": authenticationErrorResponse,
793
+ "422": validationErrorResponse,
794
+ "501": notImplementedErrorResponse,
795
+ },
796
+ },
797
+ post: {
798
+ operationId: "following.create",
799
+ summary: "Follow a target",
800
+ security: [{ bearerAuth: [] }],
801
+ requestBody: {
802
+ required: true,
803
+ content: {
804
+ "application/json": {
805
+ schema: { $ref: "#/components/schemas/FollowTargetRequest" },
806
+ },
807
+ },
808
+ },
809
+ responses: {
810
+ "201": {
811
+ description: "Created following record.",
812
+ content: {
813
+ "application/json": {
814
+ schema: { $ref: "#/components/schemas/FollowingResponse" },
815
+ },
816
+ },
817
+ },
818
+ "401": authenticationErrorResponse,
819
+ "409": conflictErrorResponse,
820
+ "422": validationErrorResponse,
821
+ "501": notImplementedErrorResponse,
822
+ },
823
+ },
824
+ },
825
+ "/following/{id}/activity": {
826
+ get: {
827
+ operationId: "following.activity.list",
828
+ summary: "Download buffered posts and boosts from one followed account",
829
+ description: "Non-consuming, actor-scoped delivery buffer of posts and boosts, without an opt-in filter. No read acknowledgment or deletion. Ordered by stable receipt sequence, not original publication time. Cursors survive deletion and remain usable when hasMore is false. Handle each item's kind; boosts distinguish sharing from original-author attribution. See docs/specs/12-incoming-activity.md for delivery and retry semantics.",
830
+ security: [{ bearerAuth: [] }],
831
+ parameters: [
832
+ { name: "id", in: "path", required: true, schema: { type: "integer", minimum: 1 } },
833
+ {
834
+ name: "limit",
835
+ in: "query",
836
+ required: false,
837
+ schema: { type: "integer", minimum: 1, maximum: 100, default: 50 },
838
+ },
839
+ {
840
+ name: "cursor",
841
+ in: "query",
842
+ required: false,
843
+ description: "Opaque continuation for this actor/following pair. Omit for the oldest available copy. Invalid/cross-scope cursors return 422.",
844
+ schema: { type: "string", minLength: 1, maxLength: 2048 },
845
+ },
846
+ ],
847
+ responses: {
848
+ "200": {
849
+ description: "Available copies at query time; concurrent explicit deletion may change later responses. Cache-Control: no-store.",
850
+ content: {
851
+ "application/json": { schema: { $ref: "#/components/schemas/IncomingActivityPage" } },
852
+ },
853
+ },
854
+ "401": authenticationErrorResponse,
855
+ "404": notFoundErrorResponse,
856
+ "422": validationErrorResponse,
857
+ "501": notImplementedErrorResponse,
858
+ },
859
+ },
860
+ delete: {
861
+ operationId: "following.activity.remove",
862
+ summary: "Remove selected buffered website copies",
863
+ description: "Atomic body removal in the selected followed account and configured actor only. Does not remove remote originals, owned publications or client bodies. Missing/already-removed/out-of-scope IDs are harmless; duplicates are coalesced. Retry identical requests after uncertain responses; removed may be zero. No read or persistence acknowledgment. Bodies are removed; minimal deduplication identities remain indefinitely.",
864
+ security: [{ bearerAuth: [] }],
865
+ parameters: [
866
+ { name: "id", in: "path", required: true, schema: { type: "integer", minimum: 1 } },
867
+ ],
868
+ requestBody: {
869
+ required: true,
870
+ description: "JSON payload, at most 16384 bytes. Validate the entire batch before changing anything.",
871
+ "x-max-body-bytes": 16384,
872
+ content: {
873
+ "application/json": {
874
+ schema: { $ref: "#/components/schemas/RemoveIncomingActivityRequest" },
875
+ example: { ids: ["b40eac11-4a38-44cc-a969-ecf2e7c4654b"] },
876
+ },
877
+ },
878
+ },
879
+ responses: {
880
+ "200": {
881
+ description: "Number of copies actually removed by this request; zero is a successful idempotent retry, not an error.",
882
+ content: {
883
+ "application/json": {
884
+ schema: { $ref: "#/components/schemas/RemoveIncomingActivityResponse" },
885
+ },
886
+ },
887
+ },
888
+ "401": authenticationErrorResponse,
889
+ "404": notFoundErrorResponse,
890
+ "413": {
891
+ description: "JSON payload exceeds 16384 bytes; no changes.",
892
+ content: {
893
+ "application/json": {
894
+ schema: { $ref: "#/components/schemas/PayloadTooLargeResponse" },
895
+ },
896
+ },
897
+ },
898
+ "422": validationErrorResponse,
899
+ "500": {
900
+ description: "Persistence failure rolls back the batch. A lost/uncertain transport response never establishes whether removal committed; retry the same IDs.",
901
+ },
902
+ "501": notImplementedErrorResponse,
903
+ },
904
+ },
905
+ },
906
+ "/following/{id}/unfollow": {
907
+ post: {
908
+ operationId: "following.unfollow",
909
+ summary: "Unfollow an accepted target or cancel a pending follow request",
910
+ security: [{ bearerAuth: [] }],
911
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
912
+ responses: {
913
+ "200": {
914
+ description: "Updated following status.",
915
+ content: {
916
+ "application/json": {
917
+ schema: { $ref: "#/components/schemas/FollowingStatusResponse" },
918
+ },
919
+ },
920
+ },
921
+ "401": authenticationErrorResponse,
922
+ "404": notFoundErrorResponse,
923
+ "409": conflictErrorResponse,
924
+ "422": validationErrorResponse,
925
+ "501": notImplementedErrorResponse,
926
+ },
927
+ },
928
+ },
929
+ "/posts/{slug}": {
930
+ get: {
931
+ operationId: "posts.get",
932
+ summary: "Get a post by slug",
933
+ security: [{ bearerAuth: [] }],
934
+ parameters: [{ name: "slug", in: "path", required: true, schema: { type: "string" } }],
935
+ responses: {
936
+ "200": {
937
+ description: "Post details.",
938
+ content: {
939
+ "application/json": {
940
+ schema: { $ref: "#/components/schemas/PostResponse" },
941
+ },
942
+ },
943
+ },
944
+ "401": authenticationErrorResponse,
945
+ "404": notFoundErrorResponse,
946
+ },
947
+ },
948
+ put: {
949
+ operationId: "posts.update",
950
+ summary: "Update a post by slug",
951
+ security: [{ bearerAuth: [] }],
952
+ parameters: [{ name: "slug", in: "path", required: true, schema: { type: "string" } }],
953
+ requestBody: {
954
+ required: true,
955
+ content: {
956
+ "application/json": {
957
+ schema: { $ref: "#/components/schemas/UpdatePostRequest" },
958
+ },
959
+ },
960
+ },
961
+ responses: {
962
+ "200": {
963
+ description: "Updated post.",
964
+ content: {
965
+ "application/json": {
966
+ schema: { $ref: "#/components/schemas/PostResponse" },
967
+ },
968
+ },
969
+ },
970
+ "401": authenticationErrorResponse,
971
+ "404": notFoundErrorResponse,
972
+ "409": conflictErrorResponse,
973
+ "422": validationErrorResponse,
974
+ },
975
+ },
976
+ delete: {
977
+ operationId: "posts.delete",
978
+ summary: "Delete a post by slug",
979
+ security: [{ bearerAuth: [] }],
980
+ parameters: [{ name: "slug", in: "path", required: true, schema: { type: "string" } }],
981
+ responses: {
982
+ "204": { description: "Post deleted." },
983
+ "401": authenticationErrorResponse,
984
+ "404": notFoundErrorResponse,
985
+ },
986
+ },
987
+ },
988
+ "/posts/{slug}/engagement": {
989
+ get: {
990
+ operationId: "posts.engagement.get",
991
+ summary: "Get post engagement summary",
992
+ security: [{ bearerAuth: [] }],
993
+ parameters: [{ name: "slug", in: "path", required: true, schema: { type: "string" } }],
994
+ responses: {
995
+ "200": {
996
+ description: "Post engagement summary.",
997
+ content: {
998
+ "application/json": {
999
+ schema: { $ref: "#/components/schemas/EngagementSummaryResponse" },
1000
+ },
1001
+ },
1002
+ },
1003
+ "401": authenticationErrorResponse,
1004
+ "404": notFoundErrorResponse,
1005
+ "501": notImplementedErrorResponse,
1006
+ },
1007
+ },
1008
+ },
1009
+ "/posts/{slug}/likes": {
1010
+ get: {
1011
+ operationId: "posts.likes.list",
1012
+ summary: "List post likes",
1013
+ security: [{ bearerAuth: [] }],
1014
+ parameters: [{ name: "slug", in: "path", required: true, schema: { type: "string" } }],
1015
+ responses: {
1016
+ "200": {
1017
+ description: "Post like actors.",
1018
+ content: {
1019
+ "application/json": {
1020
+ schema: { $ref: "#/components/schemas/EngagementActorListResponse" },
1021
+ },
1022
+ },
1023
+ },
1024
+ "401": authenticationErrorResponse,
1025
+ "404": notFoundErrorResponse,
1026
+ "501": notImplementedErrorResponse,
1027
+ },
1028
+ },
1029
+ },
1030
+ "/posts/{slug}/boosts": {
1031
+ get: {
1032
+ operationId: "posts.boosts.list",
1033
+ summary: "List post boosts",
1034
+ security: [{ bearerAuth: [] }],
1035
+ parameters: [{ name: "slug", in: "path", required: true, schema: { type: "string" } }],
1036
+ responses: {
1037
+ "200": {
1038
+ description: "Post boost actors.",
1039
+ content: {
1040
+ "application/json": {
1041
+ schema: { $ref: "#/components/schemas/EngagementActorListResponse" },
1042
+ },
1043
+ },
1044
+ },
1045
+ "401": authenticationErrorResponse,
1046
+ "404": notFoundErrorResponse,
1047
+ "501": notImplementedErrorResponse,
1048
+ },
1049
+ },
1050
+ },
1051
+ "/posts/{slug}/publish": {
1052
+ post: {
1053
+ operationId: "posts.publish",
1054
+ summary: "Publish a draft post",
1055
+ security: [{ bearerAuth: [] }],
1056
+ parameters: [{ name: "slug", in: "path", required: true, schema: { type: "string" } }],
1057
+ requestBody: {
1058
+ required: false,
1059
+ content: {
1060
+ "application/json": { schema: { $ref: "#/components/schemas/PublishPostRequest" } },
1061
+ },
1062
+ },
1063
+ responses: {
1064
+ "200": {
1065
+ description: "Published post.",
1066
+ content: {
1067
+ "application/json": { schema: { $ref: "#/components/schemas/PostResponse" } },
1068
+ },
1069
+ },
1070
+ "401": authenticationErrorResponse,
1071
+ "404": notFoundErrorResponse,
1072
+ },
1073
+ },
1074
+ },
1075
+ "/posts/{slug}/unpublish": {
1076
+ post: {
1077
+ operationId: "posts.unpublish",
1078
+ summary: "Unpublish a post",
1079
+ security: [{ bearerAuth: [] }],
1080
+ parameters: [{ name: "slug", in: "path", required: true, schema: { type: "string" } }],
1081
+ responses: {
1082
+ "200": {
1083
+ description: "Unpublished post.",
1084
+ content: {
1085
+ "application/json": { schema: { $ref: "#/components/schemas/PostResponse" } },
1086
+ },
1087
+ },
1088
+ "401": authenticationErrorResponse,
1089
+ "404": notFoundErrorResponse,
1090
+ },
1091
+ },
1092
+ },
1093
+ "/posts/{slug}/comments": {
1094
+ get: {
1095
+ operationId: "posts.comments.list",
1096
+ summary: "List comments on a post",
1097
+ security: [{ bearerAuth: [] }],
1098
+ parameters: [
1099
+ { name: "slug", in: "path", required: true, schema: { type: "string" } },
1100
+ {
1101
+ name: "status",
1102
+ in: "query",
1103
+ required: false,
1104
+ schema: {
1105
+ type: "string",
1106
+ enum: ["pending", "approved", "hidden", "all"],
1107
+ default: "approved",
1108
+ },
1109
+ },
1110
+ ],
1111
+ responses: {
1112
+ "200": {
1113
+ description: "Post comment list.",
1114
+ content: {
1115
+ "application/json": {
1116
+ schema: { $ref: "#/components/schemas/CommentListResponse" },
1117
+ },
1118
+ },
1119
+ },
1120
+ "401": authenticationErrorResponse,
1121
+ "404": notFoundErrorResponse,
1122
+ "422": validationErrorResponse,
1123
+ "501": notImplementedErrorResponse,
1124
+ },
1125
+ },
1126
+ post: {
1127
+ operationId: "posts.comments.create",
1128
+ summary: "Create a comment on a post",
1129
+ security: [{ bearerAuth: [] }],
1130
+ parameters: [{ name: "slug", in: "path", required: true, schema: { type: "string" } }],
1131
+ requestBody: {
1132
+ required: true,
1133
+ content: {
1134
+ "application/json": {
1135
+ schema: { $ref: "#/components/schemas/CreatePostCommentRequest" },
1136
+ },
1137
+ },
1138
+ },
1139
+ responses: {
1140
+ "201": {
1141
+ description: "Created comment.",
1142
+ content: {
1143
+ "application/json": {
1144
+ schema: { $ref: "#/components/schemas/CommentResponse" },
1145
+ },
1146
+ },
1147
+ },
1148
+ "401": authenticationErrorResponse,
1149
+ "404": notFoundErrorResponse,
1150
+ "422": validationErrorResponse,
1151
+ "501": notImplementedErrorResponse,
1152
+ },
1153
+ },
1154
+ },
1155
+ "/comments": {
1156
+ get: {
1157
+ operationId: "comments.list",
1158
+ summary: "List comments across posts",
1159
+ security: [{ bearerAuth: [] }],
1160
+ parameters: [
1161
+ {
1162
+ name: "status",
1163
+ in: "query",
1164
+ required: false,
1165
+ schema: {
1166
+ type: "string",
1167
+ enum: ["pending", "approved", "hidden", "all"],
1168
+ default: "all",
1169
+ },
1170
+ },
1171
+ { name: "postSlug", in: "query", required: false, schema: { type: "string" } },
1172
+ { name: "author", in: "query", required: false, schema: { type: "string" } },
1173
+ {
1174
+ name: "receivedFrom",
1175
+ in: "query",
1176
+ required: false,
1177
+ schema: { type: "string", format: "date-time" },
1178
+ },
1179
+ {
1180
+ name: "receivedTo",
1181
+ in: "query",
1182
+ required: false,
1183
+ schema: { type: "string", format: "date-time" },
1184
+ },
1185
+ ],
1186
+ responses: {
1187
+ "200": {
1188
+ description: "Comment list.",
1189
+ content: {
1190
+ "application/json": {
1191
+ schema: { $ref: "#/components/schemas/CommentListResponse" },
1192
+ },
1193
+ },
1194
+ },
1195
+ "401": authenticationErrorResponse,
1196
+ "422": validationErrorResponse,
1197
+ "501": notImplementedErrorResponse,
1198
+ },
1199
+ },
1200
+ },
1201
+ "/comments/{id}/approve": {
1202
+ post: {
1203
+ operationId: "comments.approve",
1204
+ summary: "Approve a comment",
1205
+ security: [{ bearerAuth: [] }],
1206
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
1207
+ responses: {
1208
+ "200": {
1209
+ description: "Approved comment moderation state.",
1210
+ content: {
1211
+ "application/json": {
1212
+ schema: { $ref: "#/components/schemas/CommentModerationResponse" },
1213
+ },
1214
+ },
1215
+ },
1216
+ "401": authenticationErrorResponse,
1217
+ "404": notFoundErrorResponse,
1218
+ "422": validationErrorResponse,
1219
+ "501": notImplementedErrorResponse,
1220
+ },
1221
+ },
1222
+ },
1223
+ "/comments/{id}/hide": {
1224
+ post: {
1225
+ operationId: "comments.hide",
1226
+ summary: "Hide a comment",
1227
+ security: [{ bearerAuth: [] }],
1228
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
1229
+ responses: {
1230
+ "200": {
1231
+ description: "Hidden comment moderation state.",
1232
+ content: {
1233
+ "application/json": {
1234
+ schema: { $ref: "#/components/schemas/CommentModerationResponse" },
1235
+ },
1236
+ },
1237
+ },
1238
+ "401": authenticationErrorResponse,
1239
+ "404": notFoundErrorResponse,
1240
+ "422": validationErrorResponse,
1241
+ "501": notImplementedErrorResponse,
1242
+ },
1243
+ },
1244
+ },
1245
+ },
1246
+ components: {
1247
+ securitySchemes: {
1248
+ bearerAuth: {
1249
+ type: "http",
1250
+ scheme: "bearer",
1251
+ },
1252
+ },
1253
+ schemas: {
1254
+ AuthCheckResponse: {
1255
+ type: "object",
1256
+ required: ["data"],
1257
+ properties: {
1258
+ data: {
1259
+ type: "object",
1260
+ required: ["authenticated"],
1261
+ properties: {
1262
+ authenticated: { type: "boolean", const: true },
1263
+ },
1264
+ },
1265
+ },
1266
+ },
1267
+ HealthResponse: {
1268
+ type: "object",
1269
+ required: ["status", "service", "version", "time"],
1270
+ properties: {
1271
+ status: { type: "string", const: "ok" },
1272
+ service: { type: "string", const: "slugkit-api" },
1273
+ version: { type: "string" },
1274
+ time: { type: "string", format: "date-time" },
1275
+ },
1276
+ },
1277
+ MetaResponse: {
1278
+ type: "object",
1279
+ required: ["site", "api", "software"],
1280
+ properties: {
1281
+ site: {
1282
+ type: "object",
1283
+ required: ["name", "url"],
1284
+ properties: {
1285
+ name: { type: "string" },
1286
+ url: { type: "string", format: "uri" },
1287
+ },
1288
+ },
1289
+ api: {
1290
+ type: "object",
1291
+ required: ["name", "version", "baseUrl", "openapiUrl"],
1292
+ properties: {
1293
+ name: { type: "string", const: "slugkit" },
1294
+ version: { type: "string" },
1295
+ baseUrl: { type: "string", format: "uri" },
1296
+ openapiUrl: { type: "string", format: "uri" },
1297
+ contract: {
1298
+ type: "object",
1299
+ required: ["id", "version"],
1300
+ properties: {
1301
+ id: { type: "string", const: SLUGKIT_CONTRACT_ID },
1302
+ version: { type: "string", const: SLUGKIT_CONTRACT_VERSION },
1303
+ },
1304
+ },
1305
+ },
1306
+ },
1307
+ software: {
1308
+ type: "object",
1309
+ required: ["name", "version"],
1310
+ properties: {
1311
+ name: { type: "string", const: "slugkit-template" },
1312
+ version: { type: "string" },
1313
+ },
1314
+ },
1315
+ packageMetadata: {
1316
+ type: "object",
1317
+ required: ["packages", "advisoryOnly"],
1318
+ properties: {
1319
+ template: {
1320
+ type: "object",
1321
+ required: ["packageName", "name", "version"],
1322
+ properties: {
1323
+ packageName: { type: "string" },
1324
+ name: { type: "string" },
1325
+ version: { type: "string" },
1326
+ generatedAt: { type: "string", format: "date-time" },
1327
+ },
1328
+ },
1329
+ packages: {
1330
+ type: "object",
1331
+ additionalProperties: { type: "string" },
1332
+ },
1333
+ advisoryOnly: { type: "boolean", const: true },
1334
+ migrationNotesUrl: { type: "string", format: "uri" },
1335
+ },
1336
+ },
1337
+ },
1338
+ },
1339
+ JsonValue: {
1340
+ oneOf: [
1341
+ { type: "string" },
1342
+ { type: "number" },
1343
+ { type: "boolean" },
1344
+ { type: "null" },
1345
+ { type: "array", items: { $ref: "#/components/schemas/JsonValue" } },
1346
+ {
1347
+ type: "object",
1348
+ additionalProperties: { $ref: "#/components/schemas/JsonValue" },
1349
+ },
1350
+ ],
1351
+ },
1352
+ SiteConfigCore: {
1353
+ type: "object",
1354
+ required: ["name", "url", "tagline", "description", "homepage"],
1355
+ properties: {
1356
+ name: { type: "string" },
1357
+ url: { type: "string", format: "uri" },
1358
+ tagline: { type: "string" },
1359
+ description: { type: "string" },
1360
+ homepage: {
1361
+ type: "object",
1362
+ required: ["intro", "body"],
1363
+ properties: {
1364
+ intro: { type: "string" },
1365
+ body: { type: "string" },
1366
+ },
1367
+ },
1368
+ },
1369
+ },
1370
+ SiteConfig: {
1371
+ type: "object",
1372
+ required: ["core", "custom"],
1373
+ properties: {
1374
+ core: { $ref: "#/components/schemas/SiteConfigCore" },
1375
+ custom: {
1376
+ type: "object",
1377
+ additionalProperties: { $ref: "#/components/schemas/JsonValue" },
1378
+ },
1379
+ },
1380
+ },
1381
+ SiteConfigResponse: {
1382
+ type: "object",
1383
+ required: ["data"],
1384
+ properties: {
1385
+ data: { $ref: "#/components/schemas/SiteConfig" },
1386
+ },
1387
+ },
1388
+ SiteConfigUpdateRequest: {
1389
+ type: "object",
1390
+ minProperties: 1,
1391
+ additionalProperties: false,
1392
+ properties: {
1393
+ core: {
1394
+ type: "object",
1395
+ minProperties: 1,
1396
+ additionalProperties: false,
1397
+ properties: {
1398
+ name: { type: "string", minLength: 1 },
1399
+ url: { type: "string", format: "uri" },
1400
+ tagline: { type: "string", minLength: 1 },
1401
+ description: { type: "string", minLength: 1 },
1402
+ homepage: {
1403
+ type: "object",
1404
+ minProperties: 1,
1405
+ additionalProperties: false,
1406
+ properties: {
1407
+ intro: { type: "string", minLength: 1 },
1408
+ body: { type: "string", minLength: 1 },
1409
+ },
1410
+ },
1411
+ },
1412
+ },
1413
+ custom: {
1414
+ type: "object",
1415
+ additionalProperties: { $ref: "#/components/schemas/JsonValue" },
1416
+ },
1417
+ },
1418
+ },
1419
+ ContactSummary: {
1420
+ type: "object",
1421
+ required: ["id", "name", "url"],
1422
+ properties: {
1423
+ id: { type: "integer" },
1424
+ name: { type: "string" },
1425
+ url: { type: ["string", "null"], format: "uri" },
1426
+ },
1427
+ },
1428
+ Contact: {
1429
+ type: "object",
1430
+ required: ["id", "name", "url"],
1431
+ properties: {
1432
+ id: { type: "integer" },
1433
+ name: { type: "string" },
1434
+ url: { type: ["string", "null"], format: "uri" },
1435
+ },
1436
+ },
1437
+ ContactResponse: {
1438
+ type: "object",
1439
+ required: ["data"],
1440
+ properties: { data: { $ref: "#/components/schemas/Contact" } },
1441
+ },
1442
+ ContactListResponse: {
1443
+ type: "object",
1444
+ required: ["data"],
1445
+ properties: {
1446
+ data: { type: "array", items: { $ref: "#/components/schemas/Contact" } },
1447
+ },
1448
+ },
1449
+ CreateContactRequest: {
1450
+ type: "object",
1451
+ required: ["name"],
1452
+ additionalProperties: false,
1453
+ properties: {
1454
+ name: { type: "string", minLength: 1 },
1455
+ url: { type: ["string", "null"], format: "uri" },
1456
+ },
1457
+ },
1458
+ UpdateContactRequest: {
1459
+ type: "object",
1460
+ minProperties: 1,
1461
+ additionalProperties: false,
1462
+ properties: {
1463
+ name: { type: "string", minLength: 1 },
1464
+ url: { type: ["string", "null"], format: "uri" },
1465
+ },
1466
+ },
1467
+ AccountSummary: {
1468
+ type: "object",
1469
+ required: [
1470
+ "id",
1471
+ "ownerType",
1472
+ "ownerId",
1473
+ "label",
1474
+ "url",
1475
+ "kind",
1476
+ "protocol",
1477
+ "isDefault",
1478
+ "sortOrder",
1479
+ ],
1480
+ properties: {
1481
+ id: { type: "integer" },
1482
+ ownerType: { type: "string", enum: ["contact", "source", "site"] },
1483
+ ownerId: { type: ["integer", "null"] },
1484
+ label: { type: "string" },
1485
+ url: { type: "string", format: "uri" },
1486
+ kind: { type: ["string", "null"] },
1487
+ protocol: { type: ["string", "null"] },
1488
+ isDefault: { type: "boolean" },
1489
+ sortOrder: { type: "integer" },
1490
+ },
1491
+ },
1492
+ Account: {
1493
+ type: "object",
1494
+ required: [
1495
+ "id",
1496
+ "ownerType",
1497
+ "ownerId",
1498
+ "label",
1499
+ "url",
1500
+ "avatarUrl",
1501
+ "kind",
1502
+ "protocol",
1503
+ "isDefault",
1504
+ "sortOrder",
1505
+ ],
1506
+ properties: {
1507
+ id: { type: "integer" },
1508
+ ownerType: { type: "string", enum: ["contact", "source", "site"] },
1509
+ ownerId: { type: ["integer", "null"] },
1510
+ label: { type: "string" },
1511
+ url: { type: "string", format: "uri" },
1512
+ avatarUrl: { type: ["string", "null"], format: "uri" },
1513
+ kind: { type: ["string", "null"] },
1514
+ protocol: { type: ["string", "null"] },
1515
+ isDefault: { type: "boolean" },
1516
+ sortOrder: { type: "integer" },
1517
+ },
1518
+ },
1519
+ AccountResponse: {
1520
+ type: "object",
1521
+ required: ["data"],
1522
+ properties: { data: { $ref: "#/components/schemas/Account" } },
1523
+ },
1524
+ AccountListResponse: {
1525
+ type: "object",
1526
+ required: ["data"],
1527
+ properties: { data: { type: "array", items: { $ref: "#/components/schemas/Account" } } },
1528
+ },
1529
+ CreateAccountRequest: {
1530
+ type: "object",
1531
+ required: ["ownerType", "label", "url"],
1532
+ additionalProperties: false,
1533
+ properties: {
1534
+ ownerType: { type: "string", enum: ["contact", "source", "site"] },
1535
+ ownerId: { type: "integer", minimum: 1 },
1536
+ label: { type: "string", minLength: 1 },
1537
+ url: { type: "string", format: "uri" },
1538
+ avatarUrl: { type: ["string", "null"], format: "uri" },
1539
+ kind: { type: ["string", "null"] },
1540
+ protocol: { type: ["string", "null"] },
1541
+ isDefault: { type: "boolean" },
1542
+ sortOrder: { type: "integer" },
1543
+ },
1544
+ },
1545
+ UpdateAccountRequest: {
1546
+ type: "object",
1547
+ minProperties: 1,
1548
+ additionalProperties: false,
1549
+ properties: {
1550
+ label: { type: "string", minLength: 1 },
1551
+ url: { type: "string", format: "uri" },
1552
+ avatarUrl: { type: ["string", "null"], format: "uri" },
1553
+ kind: { type: ["string", "null"] },
1554
+ protocol: { type: ["string", "null"] },
1555
+ isDefault: { type: "boolean" },
1556
+ sortOrder: { type: "integer" },
1557
+ },
1558
+ },
1559
+ Source: {
1560
+ type: "object",
1561
+ required: [
1562
+ "id",
1563
+ "name",
1564
+ "url",
1565
+ "description",
1566
+ "imageUrl",
1567
+ "faviconUrl",
1568
+ "contacts",
1569
+ "accounts",
1570
+ ],
1571
+ properties: {
1572
+ id: { type: "integer" },
1573
+ name: { type: "string" },
1574
+ url: { type: ["string", "null"], format: "uri" },
1575
+ description: { type: ["string", "null"] },
1576
+ imageUrl: { type: ["string", "null"], format: "uri" },
1577
+ faviconUrl: { type: ["string", "null"], format: "uri" },
1578
+ contacts: { type: "array", items: { $ref: "#/components/schemas/ContactSummary" } },
1579
+ accounts: { type: "array", items: { $ref: "#/components/schemas/AccountSummary" } },
1580
+ },
1581
+ },
1582
+ SourceResponse: {
1583
+ type: "object",
1584
+ required: ["data"],
1585
+ properties: { data: { $ref: "#/components/schemas/Source" } },
1586
+ },
1587
+ SourceListResponse: {
1588
+ type: "object",
1589
+ required: ["data"],
1590
+ properties: {
1591
+ data: { type: "array", items: { $ref: "#/components/schemas/Source" } },
1592
+ },
1593
+ },
1594
+ CreateSourceRequest: {
1595
+ type: "object",
1596
+ required: ["name"],
1597
+ additionalProperties: false,
1598
+ properties: {
1599
+ name: { type: "string", minLength: 1 },
1600
+ url: { type: ["string", "null"], format: "uri" },
1601
+ description: { type: ["string", "null"] },
1602
+ imageUrl: { type: ["string", "null"], format: "uri" },
1603
+ faviconUrl: { type: ["string", "null"], format: "uri" },
1604
+ contactIds: { type: "array", items: { type: "integer", minimum: 1 } },
1605
+ },
1606
+ },
1607
+ UpdateSourceRequest: {
1608
+ type: "object",
1609
+ minProperties: 1,
1610
+ additionalProperties: false,
1611
+ properties: {
1612
+ name: { type: "string", minLength: 1 },
1613
+ url: { type: ["string", "null"], format: "uri" },
1614
+ description: { type: ["string", "null"] },
1615
+ imageUrl: { type: ["string", "null"], format: "uri" },
1616
+ faviconUrl: { type: ["string", "null"], format: "uri" },
1617
+ contactIds: { type: "array", items: { type: "integer", minimum: 1 } },
1618
+ },
1619
+ },
1620
+ TagSummary: {
1621
+ type: "object",
1622
+ required: ["id", "name", "slug"],
1623
+ properties: {
1624
+ id: { type: "integer" },
1625
+ name: { type: "string" },
1626
+ slug: { type: "string" },
1627
+ },
1628
+ },
1629
+ Tag: {
1630
+ type: "object",
1631
+ required: ["id", "name", "slug", "count"],
1632
+ properties: {
1633
+ id: { type: "integer" },
1634
+ name: { type: "string" },
1635
+ slug: { type: "string" },
1636
+ count: { type: "integer" },
1637
+ },
1638
+ },
1639
+ TagListResponse: {
1640
+ type: "object",
1641
+ required: ["data"],
1642
+ properties: {
1643
+ data: { type: "array", items: { $ref: "#/components/schemas/Tag" } },
1644
+ },
1645
+ },
1646
+ Follower: {
1647
+ type: "object",
1648
+ required: ["id", "profileUrl", "displayName", "handle", "inboxUrl", "followedAt"],
1649
+ properties: {
1650
+ id: { type: "integer" },
1651
+ profileUrl: { type: "string", format: "uri" },
1652
+ displayName: { type: "string" },
1653
+ handle: { type: "string" },
1654
+ inboxUrl: { type: "string", format: "uri" },
1655
+ followedAt: { type: "string", format: "date-time" },
1656
+ },
1657
+ },
1658
+ FollowerListResponse: {
1659
+ type: "object",
1660
+ required: ["data"],
1661
+ properties: { data: { type: "array", items: { $ref: "#/components/schemas/Follower" } } },
1662
+ },
1663
+ Following: {
1664
+ type: "object",
1665
+ required: [
1666
+ "id",
1667
+ "accountId",
1668
+ "profileUrl",
1669
+ "displayName",
1670
+ "handle",
1671
+ "inboxUrl",
1672
+ "avatarUrl",
1673
+ "status",
1674
+ "lastError",
1675
+ "followedAt",
1676
+ "acceptedAt",
1677
+ "rejectedAt",
1678
+ "unfollowedAt",
1679
+ ],
1680
+ properties: {
1681
+ id: { type: "integer" },
1682
+ accountId: {
1683
+ type: "integer",
1684
+ description: "Followed contact-owned account ID. Resolve its ownerId through GET /accounts/{id} for contact attribution.",
1685
+ },
1686
+ profileUrl: { type: "string", format: "uri" },
1687
+ displayName: { type: "string" },
1688
+ handle: { type: "string" },
1689
+ inboxUrl: { type: "string", format: "uri" },
1690
+ avatarUrl: { type: ["string", "null"], format: "uri" },
1691
+ status: {
1692
+ type: "string",
1693
+ enum: ["pending", "accepted", "rejected", "failed", "cancelled", "unfollowed"],
1694
+ },
1695
+ lastError: { type: ["string", "null"] },
1696
+ followedAt: { type: "string", format: "date-time" },
1697
+ acceptedAt: { type: ["string", "null"], format: "date-time" },
1698
+ rejectedAt: { type: ["string", "null"], format: "date-time" },
1699
+ unfollowedAt: { type: ["string", "null"], format: "date-time" },
1700
+ },
1701
+ },
1702
+ IncomingPost: {
1703
+ type: "object",
1704
+ description: "Immutable first-delivery snapshot of a remote post, not an owned publication. Account/Contact attribution uses existing shapes. For posts, sharing and author attribution are equal. Remote content is untrusted; sanitize HTML before rendering. No attachment binaries are fetched.",
1705
+ required: [
1706
+ "id",
1707
+ "kind",
1708
+ "activityId",
1709
+ "objectId",
1710
+ "objectType",
1711
+ "url",
1712
+ "title",
1713
+ "contentHtml",
1714
+ "contentText",
1715
+ "publishedAt",
1716
+ "receivedAt",
1717
+ "sharingAccount",
1718
+ "sharingContact",
1719
+ "authorAccount",
1720
+ "authorContact",
1721
+ ],
1722
+ properties: {
1723
+ id: {
1724
+ type: "string",
1725
+ format: "uuid",
1726
+ description: "Opaque buffered-copy identity, not an activity or original-object ID. Treat as opaque and use only for this followed account.",
1727
+ },
1728
+ kind: { type: "string", const: "post" },
1729
+ activityId: { type: "string", format: "uri" },
1730
+ objectId: { type: "string", format: "uri" },
1731
+ objectType: { type: "string", enum: ["Note", "Article", "Page"] },
1732
+ url: { type: "string", format: "uri" },
1733
+ title: { type: ["string", "null"] },
1734
+ contentHtml: {
1735
+ type: "string",
1736
+ description: "Original remote HTML, untrusted and not sanitized. Clients must sanitize before rendering; never execute embedded scripts.",
1737
+ },
1738
+ contentText: {
1739
+ type: "string",
1740
+ description: "Plain-text derivative, not a trusted instruction or a substitute for the preserved HTML.",
1741
+ },
1742
+ publishedAt: { type: ["string", "null"], format: "date-time" },
1743
+ receivedAt: { type: "string", format: "date-time" },
1744
+ sharingAccount: { $ref: "#/components/schemas/Account" },
1745
+ sharingContact: { $ref: "#/components/schemas/Contact" },
1746
+ authorAccount: { $ref: "#/components/schemas/Account" },
1747
+ authorContact: { $ref: "#/components/schemas/Contact" },
1748
+ },
1749
+ },
1750
+ IncomingAuthorAccount: {
1751
+ description: "Original-author attribution using the existing Account shape. A unique saved contact account uses its real IDs; otherwise use an unsaved snapshot with null id/ownerType/ownerId and no persistent account/contact creation. Never pass a null ID to account-management routes.",
1752
+ oneOf: [
1753
+ { $ref: "#/components/schemas/Account" },
1754
+ {
1755
+ type: "object",
1756
+ required: [
1757
+ "id",
1758
+ "ownerType",
1759
+ "ownerId",
1760
+ "label",
1761
+ "url",
1762
+ "avatarUrl",
1763
+ "kind",
1764
+ "protocol",
1765
+ "isDefault",
1766
+ "sortOrder",
1767
+ ],
1768
+ properties: {
1769
+ id: { type: "null" },
1770
+ ownerType: { type: "null" },
1771
+ ownerId: { type: "null" },
1772
+ label: {
1773
+ type: "string",
1774
+ description: "Resolved original-author display name, or its URI if enrichment is unavailable.",
1775
+ },
1776
+ url: {
1777
+ type: "string",
1778
+ format: "uri",
1779
+ description: "Stable original-author actor URI from the canonical original.",
1780
+ },
1781
+ avatarUrl: { type: ["string", "null"], format: "uri" },
1782
+ kind: { type: "string", const: "social" },
1783
+ protocol: { type: "string", const: "activitypub" },
1784
+ isDefault: { type: "boolean", const: false },
1785
+ sortOrder: { type: "integer", const: 0 },
1786
+ },
1787
+ },
1788
+ ],
1789
+ },
1790
+ IncomingBoost: {
1791
+ type: "object",
1792
+ description: "One newly delivered boost of a remote post, including older originals. The followed sharing account is distinct from the original author. Resolve the referenced canonical original, not posting history. Distinct Announce activity IDs are distinct copies even for the same original; retries of an observed ID never resurrect a removed copy. Existing post payloads are unchanged.",
1793
+ required: [
1794
+ "id",
1795
+ "kind",
1796
+ "activityId",
1797
+ "objectId",
1798
+ "objectType",
1799
+ "url",
1800
+ "title",
1801
+ "contentHtml",
1802
+ "contentText",
1803
+ "publishedAt",
1804
+ "sharedAt",
1805
+ "receivedAt",
1806
+ "sharingAccount",
1807
+ "sharingContact",
1808
+ "authorAccount",
1809
+ "authorContact",
1810
+ ],
1811
+ properties: {
1812
+ id: {
1813
+ type: "string",
1814
+ format: "uuid",
1815
+ description: "Opaque buffered-copy identity; not the Announce or original-object ID.",
1816
+ },
1817
+ kind: { type: "string", const: "boost" },
1818
+ activityId: {
1819
+ type: "string",
1820
+ format: "uri",
1821
+ description: "Delivered Announce identity.",
1822
+ },
1823
+ objectId: {
1824
+ type: "string",
1825
+ format: "uri",
1826
+ description: "Canonical remote original-object identity, independent of this boost.",
1827
+ },
1828
+ objectType: { type: "string", enum: ["Note", "Article", "Page"] },
1829
+ url: { type: "string", format: "uri" },
1830
+ title: { type: ["string", "null"] },
1831
+ contentHtml: {
1832
+ type: "string",
1833
+ description: "Untrusted original HTML; sanitize before rendering and never execute embedded scripts.",
1834
+ },
1835
+ contentText: { type: "string" },
1836
+ publishedAt: {
1837
+ type: ["string", "null"],
1838
+ format: "date-time",
1839
+ description: "Original publication time, not the boost's age or receipt order.",
1840
+ },
1841
+ sharedAt: {
1842
+ type: ["string", "null"],
1843
+ format: "date-time",
1844
+ description: "Announce publication time, if supplied; not proof of receipt.",
1845
+ },
1846
+ receivedAt: { type: "string", format: "date-time" },
1847
+ sharingAccount: { $ref: "#/components/schemas/Account" },
1848
+ sharingContact: { $ref: "#/components/schemas/Contact" },
1849
+ authorAccount: { $ref: "#/components/schemas/IncomingAuthorAccount" },
1850
+ authorContact: {
1851
+ oneOf: [{ $ref: "#/components/schemas/Contact" }, { type: "null" }],
1852
+ description: "Frozen known Contact attribution, or null for an unsaved/ambiguous original author.",
1853
+ },
1854
+ },
1855
+ },
1856
+ IncomingActivityPage: {
1857
+ type: "object",
1858
+ required: ["data", "meta"],
1859
+ properties: {
1860
+ data: {
1861
+ type: "array",
1862
+ maxItems: 100,
1863
+ items: {
1864
+ oneOf: [
1865
+ { $ref: "#/components/schemas/IncomingPost" },
1866
+ { $ref: "#/components/schemas/IncomingBoost" },
1867
+ ],
1868
+ discriminator: {
1869
+ propertyName: "kind",
1870
+ mapping: {
1871
+ post: "#/components/schemas/IncomingPost",
1872
+ boost: "#/components/schemas/IncomingBoost",
1873
+ },
1874
+ },
1875
+ },
1876
+ },
1877
+ meta: {
1878
+ type: "object",
1879
+ required: ["nextCursor", "hasMore", "limit"],
1880
+ properties: {
1881
+ nextCursor: {
1882
+ type: "string",
1883
+ description: "Continuation after the last returned copy, or unchanged position for an empty page; usable for polling new arrivals. Advancing this cursor is a client choice, not proof of persistence.",
1884
+ },
1885
+ hasMore: {
1886
+ type: "boolean",
1887
+ description: "More copies were available at query time, not a guarantee against concurrent deletion.",
1888
+ },
1889
+ limit: { type: "integer", minimum: 1, maximum: 100 },
1890
+ },
1891
+ },
1892
+ },
1893
+ },
1894
+ RemoveIncomingActivityRequest: {
1895
+ type: "object",
1896
+ additionalProperties: false,
1897
+ required: ["ids"],
1898
+ properties: {
1899
+ ids: {
1900
+ type: "array",
1901
+ minItems: 1,
1902
+ maxItems: 100,
1903
+ items: {
1904
+ type: "string",
1905
+ format: "uuid",
1906
+ pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
1907
+ },
1908
+ },
1909
+ },
1910
+ },
1911
+ RemoveIncomingActivityResponse: {
1912
+ type: "object",
1913
+ required: ["data"],
1914
+ properties: {
1915
+ data: {
1916
+ type: "object",
1917
+ required: ["removed"],
1918
+ properties: { removed: { type: "integer", minimum: 0, maximum: 100 } },
1919
+ },
1920
+ },
1921
+ },
1922
+ FollowingResponse: {
1923
+ type: "object",
1924
+ required: ["data"],
1925
+ properties: { data: { $ref: "#/components/schemas/Following" } },
1926
+ },
1927
+ FollowingListResponse: {
1928
+ type: "object",
1929
+ required: ["data"],
1930
+ properties: { data: { type: "array", items: { $ref: "#/components/schemas/Following" } } },
1931
+ },
1932
+ FollowTargetRequest: {
1933
+ type: "object",
1934
+ required: ["target"],
1935
+ additionalProperties: false,
1936
+ properties: { target: { type: "string", minLength: 1 } },
1937
+ },
1938
+ FollowingStatus: {
1939
+ type: "object",
1940
+ required: ["id", "status", "unfollowedAt"],
1941
+ properties: {
1942
+ id: { type: "integer" },
1943
+ status: { type: "string", enum: ["cancelled", "unfollowed"] },
1944
+ unfollowedAt: { type: ["string", "null"], format: "date-time" },
1945
+ },
1946
+ },
1947
+ FollowingStatusResponse: {
1948
+ type: "object",
1949
+ required: ["data"],
1950
+ properties: { data: { $ref: "#/components/schemas/FollowingStatus" } },
1951
+ },
1952
+ EngagementSummary: {
1953
+ type: "object",
1954
+ required: ["postSlug", "likes", "boosts", "comments"],
1955
+ properties: {
1956
+ postSlug: { type: "string" },
1957
+ likes: {
1958
+ type: "object",
1959
+ required: ["count"],
1960
+ properties: { count: { type: "integer" } },
1961
+ },
1962
+ boosts: {
1963
+ type: "object",
1964
+ required: ["count"],
1965
+ properties: { count: { type: "integer" } },
1966
+ },
1967
+ comments: {
1968
+ type: "object",
1969
+ required: ["count", "pendingCount"],
1970
+ properties: { count: { type: "integer" }, pendingCount: { type: "integer" } },
1971
+ },
1972
+ },
1973
+ },
1974
+ EngagementSummaryResponse: {
1975
+ type: "object",
1976
+ required: ["data"],
1977
+ properties: { data: { $ref: "#/components/schemas/EngagementSummary" } },
1978
+ },
1979
+ EngagementActor: {
1980
+ type: "object",
1981
+ required: ["profileUrl", "displayName", "handle", "activityUrl", "objectUrl", "receivedAt"],
1982
+ properties: {
1983
+ profileUrl: { type: "string", format: "uri" },
1984
+ displayName: { type: "string" },
1985
+ handle: { type: "string" },
1986
+ activityUrl: { type: "string", format: "uri" },
1987
+ objectUrl: { type: "string", format: "uri" },
1988
+ receivedAt: { type: "string", format: "date-time" },
1989
+ },
1990
+ },
1991
+ EngagementActorListResponse: {
1992
+ type: "object",
1993
+ required: ["data"],
1994
+ properties: {
1995
+ data: { type: "array", items: { $ref: "#/components/schemas/EngagementActor" } },
1996
+ },
1997
+ },
1998
+ Media: {
1999
+ type: "object",
2000
+ required: ["id", "filename", "mimeType", "key", "altText", "url", "createdAt"],
2001
+ properties: {
2002
+ id: { type: "integer" },
2003
+ filename: { type: "string" },
2004
+ mimeType: { type: "string" },
2005
+ key: { type: "string" },
2006
+ altText: { type: ["string", "null"] },
2007
+ url: { type: "string", format: "uri" },
2008
+ createdAt: { type: "string", format: "date-time" },
2009
+ },
2010
+ },
2011
+ MediaResponse: {
2012
+ type: "object",
2013
+ required: ["data"],
2014
+ properties: { data: { $ref: "#/components/schemas/Media" } },
2015
+ },
2016
+ UploadMediaRequest: {
2017
+ type: "object",
2018
+ required: ["file"],
2019
+ properties: {
2020
+ file: { type: "string", format: "binary" },
2021
+ altText: { type: "string" },
2022
+ key: { type: "string" },
2023
+ },
2024
+ },
2025
+ Post: {
2026
+ type: "object",
2027
+ required: [
2028
+ "id",
2029
+ "slug",
2030
+ "type",
2031
+ "title",
2032
+ "content",
2033
+ "excerpt",
2034
+ "url",
2035
+ "bannerUrl",
2036
+ "sourceId",
2037
+ "source",
2038
+ "creditContactIds",
2039
+ "creditedContacts",
2040
+ "tags",
2041
+ "publishedAt",
2042
+ "createdAt",
2043
+ "updatedAt",
2044
+ ],
2045
+ properties: {
2046
+ id: { type: "integer" },
2047
+ slug: { type: "string" },
2048
+ type: { type: "string", enum: ["article", "link", "note"] },
2049
+ title: { type: ["string", "null"] },
2050
+ content: { type: "string" },
2051
+ excerpt: { type: ["string", "null"] },
2052
+ url: { type: ["string", "null"], format: "uri" },
2053
+ bannerUrl: { type: ["string", "null"], format: "uri" },
2054
+ sourceId: { type: ["integer", "null"] },
2055
+ source: {
2056
+ oneOf: [{ $ref: "#/components/schemas/Source" }, { type: "null" }],
2057
+ },
2058
+ creditContactIds: {
2059
+ type: "array",
2060
+ description: "Contact IDs credited for external, source, or linked-content context. These are not local post authors.",
2061
+ items: { type: "integer" },
2062
+ },
2063
+ creditedContacts: {
2064
+ type: "array",
2065
+ description: "Contacts credited for external, source, or linked-content context. These are not local post authors.",
2066
+ items: { $ref: "#/components/schemas/ContactSummary" },
2067
+ },
2068
+ tags: { type: "array", items: { $ref: "#/components/schemas/TagSummary" } },
2069
+ publishedAt: { type: ["string", "null"], format: "date-time" },
2070
+ createdAt: { type: "string", format: "date-time" },
2071
+ updatedAt: { type: "string", format: "date-time" },
2072
+ },
2073
+ },
2074
+ PostListItem: {
2075
+ type: "object",
2076
+ required: [
2077
+ "id",
2078
+ "slug",
2079
+ "type",
2080
+ "title",
2081
+ "excerpt",
2082
+ "url",
2083
+ "bannerUrl",
2084
+ "sourceId",
2085
+ "source",
2086
+ "creditContactIds",
2087
+ "creditedContacts",
2088
+ "tags",
2089
+ "publishedAt",
2090
+ "createdAt",
2091
+ "updatedAt",
2092
+ ],
2093
+ properties: {
2094
+ id: { type: "integer" },
2095
+ slug: { type: "string" },
2096
+ type: { type: "string", enum: ["article", "link", "note"] },
2097
+ title: { type: ["string", "null"] },
2098
+ excerpt: { type: ["string", "null"] },
2099
+ url: { type: ["string", "null"], format: "uri" },
2100
+ bannerUrl: { type: ["string", "null"], format: "uri" },
2101
+ sourceId: { type: ["integer", "null"] },
2102
+ source: {
2103
+ oneOf: [{ $ref: "#/components/schemas/Source" }, { type: "null" }],
2104
+ },
2105
+ creditContactIds: {
2106
+ type: "array",
2107
+ description: "Contact IDs credited for external, source, or linked-content context. These are not local post authors.",
2108
+ items: { type: "integer" },
2109
+ },
2110
+ creditedContacts: {
2111
+ type: "array",
2112
+ description: "Contacts credited for external, source, or linked-content context. These are not local post authors.",
2113
+ items: { $ref: "#/components/schemas/ContactSummary" },
2114
+ },
2115
+ tags: { type: "array", items: { $ref: "#/components/schemas/TagSummary" } },
2116
+ publishedAt: { type: ["string", "null"], format: "date-time" },
2117
+ createdAt: { type: "string", format: "date-time" },
2118
+ updatedAt: { type: "string", format: "date-time" },
2119
+ },
2120
+ },
2121
+ PostResponse: {
2122
+ type: "object",
2123
+ required: ["data"],
2124
+ properties: { data: { $ref: "#/components/schemas/Post" } },
2125
+ },
2126
+ PostListResponse: {
2127
+ type: "object",
2128
+ required: ["data", "meta"],
2129
+ properties: {
2130
+ data: { type: "array", items: { $ref: "#/components/schemas/PostListItem" } },
2131
+ meta: {
2132
+ type: "object",
2133
+ required: ["limit", "offset"],
2134
+ properties: { limit: { type: "integer" }, offset: { type: "integer" } },
2135
+ },
2136
+ },
2137
+ },
2138
+ Comment: {
2139
+ type: "object",
2140
+ required: [
2141
+ "id",
2142
+ "postSlug",
2143
+ "activityUrl",
2144
+ "objectUrl",
2145
+ "authorProfileUrl",
2146
+ "authorName",
2147
+ "authorHandle",
2148
+ "contentHtml",
2149
+ "contentText",
2150
+ "inReplyToUrl",
2151
+ "moderationStatus",
2152
+ "publishedAt",
2153
+ "receivedAt",
2154
+ "moderatedAt",
2155
+ ],
2156
+ properties: {
2157
+ id: { type: "integer" },
2158
+ postSlug: { type: "string" },
2159
+ activityUrl: { type: "string", format: "uri" },
2160
+ objectUrl: { type: "string", format: "uri" },
2161
+ authorProfileUrl: { type: "string", format: "uri" },
2162
+ authorName: { type: "string" },
2163
+ authorHandle: { type: "string" },
2164
+ contentHtml: { type: "string" },
2165
+ contentText: { type: "string" },
2166
+ inReplyToUrl: { type: "string", format: "uri" },
2167
+ moderationStatus: { type: "string", enum: ["pending", "approved", "hidden"] },
2168
+ publishedAt: { type: "string", format: "date-time" },
2169
+ receivedAt: { type: "string", format: "date-time" },
2170
+ moderatedAt: { type: ["string", "null"], format: "date-time" },
2171
+ },
2172
+ },
2173
+ CommentListItem: {
2174
+ type: "object",
2175
+ required: [
2176
+ "id",
2177
+ "postSlug",
2178
+ "authorProfileUrl",
2179
+ "authorName",
2180
+ "authorHandle",
2181
+ "contentText",
2182
+ "moderationStatus",
2183
+ "receivedAt",
2184
+ ],
2185
+ properties: {
2186
+ id: { type: "integer" },
2187
+ postSlug: { type: "string" },
2188
+ authorProfileUrl: { type: "string", format: "uri" },
2189
+ authorName: { type: "string" },
2190
+ authorHandle: { type: "string" },
2191
+ contentText: { type: "string" },
2192
+ moderationStatus: { type: "string", enum: ["pending", "approved", "hidden"] },
2193
+ receivedAt: { type: "string", format: "date-time" },
2194
+ },
2195
+ },
2196
+ CommentListResponse: {
2197
+ type: "object",
2198
+ required: ["data"],
2199
+ properties: {
2200
+ data: { type: "array", items: { $ref: "#/components/schemas/CommentListItem" } },
2201
+ },
2202
+ },
2203
+ CommentResponse: {
2204
+ type: "object",
2205
+ required: ["data"],
2206
+ properties: { data: { $ref: "#/components/schemas/Comment" } },
2207
+ },
2208
+ CreatePostCommentRequest: {
2209
+ type: "object",
2210
+ required: ["content"],
2211
+ additionalProperties: false,
2212
+ properties: { content: { type: "string", minLength: 1 } },
2213
+ },
2214
+ CommentModeration: {
2215
+ type: "object",
2216
+ required: ["id", "moderationStatus", "moderatedAt"],
2217
+ properties: {
2218
+ id: { type: "integer" },
2219
+ moderationStatus: { type: "string", enum: ["approved", "hidden"] },
2220
+ moderatedAt: { type: "string", format: "date-time" },
2221
+ },
2222
+ },
2223
+ CommentModerationResponse: {
2224
+ type: "object",
2225
+ required: ["data"],
2226
+ properties: { data: { $ref: "#/components/schemas/CommentModeration" } },
2227
+ },
2228
+ CreatePostRequest: {
2229
+ type: "object",
2230
+ required: ["type", "slug", "content"],
2231
+ properties: {
2232
+ type: { type: "string", enum: ["article", "link", "note"] },
2233
+ slug: { type: "string" },
2234
+ title: { type: ["string", "null"] },
2235
+ content: { type: "string" },
2236
+ excerpt: { type: ["string", "null"] },
2237
+ url: { type: ["string", "null"], format: "uri" },
2238
+ bannerUrl: { type: ["string", "null"], format: "uri" },
2239
+ sourceId: { type: ["integer", "null"] },
2240
+ creditContactIds: {
2241
+ type: "array",
2242
+ description: "Contact IDs credited for external, source, or linked-content context. These are not local post authors.",
2243
+ items: { type: "integer" },
2244
+ },
2245
+ tagSlugs: { type: "array", items: { type: "string" } },
2246
+ publishedAt: {
2247
+ type: ["string", "null"],
2248
+ format: "date-time",
2249
+ description: "Optional original publish timestamp for migration/import workflows. When supplied on create, the post is created as already published without ActivityPub follower delivery.",
2250
+ },
2251
+ },
2252
+ },
2253
+ UpdatePostRequest: {
2254
+ type: "object",
2255
+ minProperties: 1,
2256
+ properties: {
2257
+ slug: { type: "string" },
2258
+ title: { type: ["string", "null"] },
2259
+ content: { type: "string" },
2260
+ excerpt: { type: ["string", "null"] },
2261
+ url: { type: ["string", "null"], format: "uri" },
2262
+ bannerUrl: { type: ["string", "null"], format: "uri" },
2263
+ sourceId: { type: ["integer", "null"] },
2264
+ creditContactIds: {
2265
+ type: "array",
2266
+ description: "Contact IDs credited for external, source, or linked-content context. These are not local post authors.",
2267
+ items: { type: "integer" },
2268
+ },
2269
+ tagSlugs: { type: "array", items: { type: "string" } },
2270
+ publishedAt: {
2271
+ type: ["string", "null"],
2272
+ format: "date-time",
2273
+ description: "Optional explicit publish timestamp for migration/import corrections.",
2274
+ },
2275
+ },
2276
+ },
2277
+ PublishPostRequest: {
2278
+ type: "object",
2279
+ properties: {
2280
+ publishedAt: {
2281
+ type: ["string", "null"],
2282
+ format: "date-time",
2283
+ description: "Optional explicit publish timestamp. When omitted, publishing uses the current server time and normal follower delivery behavior.",
2284
+ },
2285
+ },
2286
+ },
2287
+ SuccessResponse: {
2288
+ type: "object",
2289
+ required: ["data"],
2290
+ properties: {
2291
+ data: true,
2292
+ },
2293
+ },
2294
+ FieldError: {
2295
+ type: "object",
2296
+ required: ["field", "message"],
2297
+ properties: {
2298
+ field: { type: "string" },
2299
+ message: { type: "string" },
2300
+ },
2301
+ },
2302
+ ErrorResponse: errorSchema,
2303
+ ValidationErrorResponse: errorSchema,
2304
+ NotFoundResponse: errorSchema,
2305
+ ConflictResponse: errorSchema,
2306
+ AuthenticationErrorResponse: errorSchema,
2307
+ PayloadTooLargeResponse: errorSchema,
2308
+ StorageErrorResponse: errorSchema,
2309
+ UnsupportedMediaTypeResponse: errorSchema,
2310
+ NotImplementedResponse: {
2311
+ type: "object",
2312
+ required: ["error"],
2313
+ properties: {
2314
+ error: {
2315
+ type: "object",
2316
+ required: ["code", "message", "operation"],
2317
+ properties: {
2318
+ code: { type: "string", const: "NOT_IMPLEMENTED" },
2319
+ message: { type: "string", const: "This site does not implement this operation." },
2320
+ operation: { type: "string" },
2321
+ },
2322
+ },
2323
+ },
2324
+ },
2325
+ },
2326
+ },
2327
+ };