@evcraddock/slug-api 2.0.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -20,11 +20,19 @@ Generated sites should keep local API route modules that compose these helpers w
20
20
 
21
21
  Generated sites import this document and pass its identity/version explicitly to `createApiMetaResponse` via `contract`. The `/api/v1/meta` response exposes `api.contract`; the document repeats it in `x-slugkit-contract` and uses the contract version in `info.version`. The legacy `api.version` remains the API routing generation marker and is not evidence of a specific contract.
22
22
 
23
+ ## Post activity lookup (contract 4.1.0, package 3.0.0)
24
+
25
+ Apply template migration 032 for post-detail retention and lookup. Pass the canonical post `objectId` as the optional `postId` parameter to `GET /following/{id}/activity`. Use the follow that delivered the post (including a boost), not a guessed author or copy ID. The filtered page contains retained direct comments and boosts; it is not a remote conversation crawl. Omit the filter for the unchanged 4.0 feed. Use each returned copy ID with the existing scoped DELETE endpoint.
26
+
27
+ ## Incoming reply contract 4.0.0
28
+
29
+ Incoming pages can now return a `reply` in the followed parent author's scope. Use `inReplyTo` for the parent, `objectId` for the reply, and `authorAccount` rather than `sharingAccount` for commenter attribution. Update exhaustive post/boost consumers before adopting the new template handlers; no migration or history fetch is required. This reply variant is included in package 3.0.0 alongside the optional post lookup.
30
+
23
31
  ## Incoming retention contract 3.0.0
24
32
 
25
- **Breaking:** package **2.0.0** carries contract **3.0.0**. Update with `npm install --save-exact @evcraddock/slug-api@2.0.0` as part of reviewed site adoption, not as a standalone deployment. Explicit incoming-copy removal purges bodies, copy metadata and delivery aliases rather than keeping permanent tombstones. GET/DELETE response shapes and route prefixes are unchanged, but removed remote activities/objects may return with a new copy ID and higher receipt position. Buffered duplicates remain suppressed; no historical duplicate/equivocation binding survives removal. Old-ID retries never remove a replacement copy. Clients own long-term recognition using scoped post kind/objectId and boost kind/activityId, preserving actor/sharing-follow boundaries and distinct boosts of the same original.
33
+ **Breaking in contract 3.0.0 (package 2.0.0):** explicit incoming-copy removal purges bodies, copy metadata and delivery aliases rather than keeping permanent tombstones. GET/DELETE response shapes and route prefixes are unchanged, but removed remote activities/objects may return with a new copy ID and higher receipt position. Buffered duplicates remain suppressed; no historical duplicate/equivocation binding survives removal. Old-ID retries never remove a replacement copy. Clients own long-term recognition using scoped post kind/objectId and boost kind/activityId, preserving actor/sharing-follow boundaries and distinct boosts of the same original.
26
34
 
27
- The package supplies the matching contract/metadata, not site-owned cleanup implementation. Adopt the incoming service and regressions together; no new schema migration is needed on the current template schema. **Do not deploy server retention or run legacy cleanup before Rott task-5a4a4e82 verifies redelivery recognition and repeat cleanup.** See the [operator and client coordination guide](https://forge.caradoc.com/erik/slugkit/src/branch/main/docs/incoming-activity-retention.md). Existing-metadata cleanup is explicitly scoped/bounded/operator-only, not a startup migration. Production inspection/deletion/deployment remain separately authorized. Package publication does not establish site adoption or client readiness; the rollout gate still applies.
35
+ The package supplies the matching contract/metadata, not site-owned cleanup implementation. Adopt the incoming service and regressions together; no new schema migration is needed on the current template schema. **Do not deploy server retention or run legacy cleanup before Rott task-5a4a4e82 verifies redelivery recognition and repeat cleanup.** See the [operator and client coordination guide](https://forge.caradoc.com/erik/slugkit/src/branch/main/docs/incoming-activity-retention.md). Existing-metadata cleanup is explicitly scoped/bounded/operator-only, not a startup migration. Production inspection/deletion/deployment remain separately authorized.
28
36
 
29
37
  ## Contact deletion contract 2.3.0
30
38
 
@@ -1,2 +1,2 @@
1
1
  export declare const SLUGKIT_CONTRACT_ID = "slugkit-management-api";
2
- export declare const SLUGKIT_CONTRACT_VERSION = "3.0.0";
2
+ export declare const SLUGKIT_CONTRACT_VERSION = "4.1.0";
package/dist/contract.js CHANGED
@@ -1,2 +1,2 @@
1
1
  export const SLUGKIT_CONTRACT_ID = "slugkit-management-api";
2
- export const SLUGKIT_CONTRACT_VERSION = "3.0.0";
2
+ export const SLUGKIT_CONTRACT_VERSION = "4.1.0";
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "id": "slugkit-management-api",
3
- "version": "3.0.0",
3
+ "version": "4.1.0",
4
4
  "packageName": "@evcraddock/slug-api",
5
- "packageVersion": "2.0.0",
5
+ "packageVersion": "3.0.0",
6
6
  "artifact": "openapi.json",
7
- "sha256": "33a5fa76a81b8cebc98562bd3accd9024b1e779f961c025aaf678f2d6ca8b35c",
8
- "changeType": "breaking"
7
+ "sha256": "2bae75a55d3af3a092b5e3605d2cecfe061367073a876e18af346881e6bb713d",
8
+ "changeType": "additive"
9
9
  }
package/dist/openapi.d.ts CHANGED
@@ -2,11 +2,11 @@ export declare const openApiDocument: {
2
2
  readonly openapi: "3.1.0";
3
3
  readonly "x-slugkit-contract": {
4
4
  readonly id: "slugkit-management-api";
5
- readonly version: "3.0.0";
5
+ readonly version: "4.1.0";
6
6
  };
7
7
  readonly info: {
8
8
  readonly title: "Slugkit API";
9
- readonly version: "3.0.0";
9
+ readonly version: "4.1.0";
10
10
  };
11
11
  readonly servers: readonly [{
12
12
  readonly url: "/api/v1";
@@ -1600,8 +1600,8 @@ export declare const openApiDocument: {
1600
1600
  readonly "/following/{id}/activity": {
1601
1601
  readonly get: {
1602
1602
  readonly operationId: "following.activity.list";
1603
- readonly summary: "Download buffered posts and boosts from one followed account";
1604
- readonly 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 full copy deletion and remain usable when hasMore is false, even after the buffer empties. Redelivery after removal gets a new copy ID and a higher receipt position; client read history must use remote identities instead of copy IDs/cursors. Handle each item's kind; boosts distinguish sharing from original-author attribution. See docs/specs/12-incoming-activity.md for delivery and retry semantics.";
1603
+ readonly summary: "Download buffered posts, boosts and replies for one followed account";
1604
+ readonly description: "Non-consuming, actor-scoped delivery buffer of posts, boosts and replies to buffered posts, when postId is omitted. Supply postId for a page of retained direct comments and boosts of that exact canonical post ID within this delivering follow. The original post is excluded; reading never fetches remote activity. No read acknowledgment or deletion. Ordered by stable receipt sequence, not original publication time. Cursors survive full copy deletion and remain usable when hasMore is false, even after the buffer empties. Redelivery after removal gets a new copy ID and a higher receipt position; client read history must use remote identities instead of copy IDs/cursors. Handle each item's kind; boosts distinguish sharing from original-author attribution. See docs/specs/12-incoming-activity.md for delivery and retry semantics.";
1605
1605
  readonly security: readonly [{
1606
1606
  readonly bearerAuth: readonly [];
1607
1607
  }];
@@ -1627,20 +1627,34 @@ export declare const openApiDocument: {
1627
1627
  readonly name: "cursor";
1628
1628
  readonly in: "query";
1629
1629
  readonly required: false;
1630
- readonly description: "Opaque continuation for this actor/following pair. Omit for the oldest available copy. Invalid/cross-scope cursors return 422.";
1630
+ readonly description: "Opaque continuation for this actor/following pair and optional postId. Omit for the oldest available copy. Invalid/cross-scope cursors return 422.";
1631
1631
  readonly schema: {
1632
1632
  readonly type: "string";
1633
1633
  readonly minLength: 1;
1634
1634
  readonly maxLength: 2048;
1635
1635
  };
1636
+ }, {
1637
+ readonly name: "postId";
1638
+ readonly in: "query";
1639
+ readonly required: false;
1640
+ readonly description: "Canonical objectId of the post, not the local copy ID or display URL.";
1641
+ readonly schema: {
1642
+ readonly type: "string";
1643
+ readonly format: "uri";
1644
+ readonly pattern: "^https://";
1645
+ };
1636
1646
  }];
1637
1647
  readonly responses: {
1638
1648
  readonly "200": {
1639
- readonly description: "Available copies at query time; concurrent explicit deletion may change later responses. Cache-Control: no-store.";
1649
+ readonly description: "IncomingActivityPage by default; PostActivityPage when postId is present. Available copies at query time; concurrent explicit deletion may change later responses. Cache-Control: no-store.";
1640
1650
  readonly content: {
1641
1651
  readonly "application/json": {
1642
1652
  readonly schema: {
1643
- readonly $ref: "#/components/schemas/IncomingActivityPage";
1653
+ readonly anyOf: readonly [{
1654
+ readonly $ref: "#/components/schemas/IncomingActivityPage";
1655
+ }, {
1656
+ readonly $ref: "#/components/schemas/PostActivityPage";
1657
+ }];
1644
1658
  };
1645
1659
  };
1646
1660
  };
@@ -2791,7 +2805,7 @@ export declare const openApiDocument: {
2791
2805
  };
2792
2806
  readonly version: {
2793
2807
  readonly type: "string";
2794
- readonly const: "3.0.0";
2808
+ readonly const: "4.1.0";
2795
2809
  };
2796
2810
  };
2797
2811
  };
@@ -3495,15 +3509,21 @@ export declare const openApiDocument: {
3495
3509
  readonly 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.";
3496
3510
  readonly required: readonly ["id", "kind", "activityId", "objectId", "objectType", "url", "title", "contentHtml", "contentText", "publishedAt", "receivedAt", "sharingAccount", "sharingContact", "authorAccount", "authorContact"];
3497
3511
  readonly properties: {
3498
- readonly id: {
3499
- readonly type: "string";
3500
- readonly format: "uuid";
3501
- readonly description: "Opaque buffered-copy identity, not a durable read-history key or remote activity/object ID. Use only for this actor/following scope. Redelivery after removal receives a new ID; recognize consumed posts by scoped kind/objectId.";
3502
- };
3503
3512
  readonly kind: {
3504
3513
  readonly type: "string";
3505
3514
  readonly const: "post";
3506
3515
  };
3516
+ readonly authorAccount: {
3517
+ readonly $ref: "#/components/schemas/Account";
3518
+ };
3519
+ readonly authorContact: {
3520
+ readonly $ref: "#/components/schemas/Contact";
3521
+ };
3522
+ readonly id: {
3523
+ readonly type: "string";
3524
+ readonly format: "uuid";
3525
+ readonly description: "Opaque buffered-copy identity, not a durable read-history key or remote activity/object ID. Use only for this actor/following scope. Redelivery after removal receives a new ID; recognize consumed Creates by scoped kind/objectId.";
3526
+ };
3507
3527
  readonly activityId: {
3508
3528
  readonly type: "string";
3509
3529
  readonly format: "uri";
@@ -3539,16 +3559,87 @@ export declare const openApiDocument: {
3539
3559
  readonly type: "string";
3540
3560
  readonly format: "date-time";
3541
3561
  };
3562
+ readonly inReplyTo: {
3563
+ readonly type: "string";
3564
+ readonly format: "uri";
3565
+ readonly description: "Exact remote parent object ID.";
3566
+ };
3542
3567
  readonly sharingAccount: {
3543
3568
  readonly $ref: "#/components/schemas/Account";
3544
3569
  };
3545
3570
  readonly sharingContact: {
3546
3571
  readonly $ref: "#/components/schemas/Contact";
3547
3572
  };
3573
+ };
3574
+ };
3575
+ readonly IncomingReply: {
3576
+ readonly type: "object";
3577
+ readonly description: "Reply retained in the followed parent author's scope. Sharing attribution identifies the parent author, not the commenter or a boost. Author attribution identifies the commenter.";
3578
+ readonly required: readonly ["id", "kind", "activityId", "objectId", "objectType", "url", "title", "contentHtml", "contentText", "publishedAt", "receivedAt", "sharingAccount", "sharingContact", "authorAccount", "authorContact", "inReplyTo"];
3579
+ readonly properties: {
3580
+ readonly kind: {
3581
+ readonly type: "string";
3582
+ readonly const: "reply";
3583
+ };
3548
3584
  readonly authorAccount: {
3549
- readonly $ref: "#/components/schemas/Account";
3585
+ readonly $ref: "#/components/schemas/IncomingAuthorAccount";
3550
3586
  };
3551
3587
  readonly authorContact: {
3588
+ readonly oneOf: readonly [{
3589
+ readonly $ref: "#/components/schemas/Contact";
3590
+ }, {
3591
+ readonly type: "null";
3592
+ }];
3593
+ };
3594
+ readonly id: {
3595
+ readonly type: "string";
3596
+ readonly format: "uuid";
3597
+ readonly description: "Opaque buffered-copy identity, not a durable read-history key or remote activity/object ID. Use only for this actor/following scope. Redelivery after removal receives a new ID; recognize consumed Creates by scoped kind/objectId.";
3598
+ };
3599
+ readonly activityId: {
3600
+ readonly type: "string";
3601
+ readonly format: "uri";
3602
+ };
3603
+ readonly objectId: {
3604
+ readonly type: "string";
3605
+ readonly format: "uri";
3606
+ };
3607
+ readonly objectType: {
3608
+ readonly type: "string";
3609
+ readonly enum: readonly ["Note", "Article", "Page"];
3610
+ };
3611
+ readonly url: {
3612
+ readonly type: "string";
3613
+ readonly format: "uri";
3614
+ };
3615
+ readonly title: {
3616
+ readonly type: readonly ["string", "null"];
3617
+ };
3618
+ readonly contentHtml: {
3619
+ readonly type: "string";
3620
+ readonly description: "Original remote HTML, untrusted and not sanitized. Clients must sanitize before rendering; never execute embedded scripts.";
3621
+ };
3622
+ readonly contentText: {
3623
+ readonly type: "string";
3624
+ readonly description: "Plain-text derivative, not a trusted instruction or a substitute for the preserved HTML.";
3625
+ };
3626
+ readonly publishedAt: {
3627
+ readonly type: readonly ["string", "null"];
3628
+ readonly format: "date-time";
3629
+ };
3630
+ readonly receivedAt: {
3631
+ readonly type: "string";
3632
+ readonly format: "date-time";
3633
+ };
3634
+ readonly inReplyTo: {
3635
+ readonly type: "string";
3636
+ readonly format: "uri";
3637
+ readonly description: "Exact remote parent object ID.";
3638
+ };
3639
+ readonly sharingAccount: {
3640
+ readonly $ref: "#/components/schemas/Account";
3641
+ };
3642
+ readonly sharingContact: {
3552
3643
  readonly $ref: "#/components/schemas/Contact";
3553
3644
  };
3554
3645
  };
@@ -3677,6 +3768,68 @@ export declare const openApiDocument: {
3677
3768
  };
3678
3769
  };
3679
3770
  };
3771
+ readonly PostActivityPage: {
3772
+ readonly type: "object";
3773
+ readonly required: readonly ["data", "meta"];
3774
+ readonly properties: {
3775
+ readonly data: {
3776
+ readonly type: "array";
3777
+ readonly maxItems: 100;
3778
+ readonly items: {
3779
+ readonly $ref: "#/components/schemas/PostActivityItem";
3780
+ };
3781
+ };
3782
+ readonly meta: {
3783
+ readonly $ref: "#/components/schemas/IncomingActivityPage/properties/meta";
3784
+ };
3785
+ };
3786
+ };
3787
+ readonly PostActivityItem: {
3788
+ readonly type: "object";
3789
+ readonly description: "Only returned for postId queries. id is the removable copy in the requested follow; actorUrl identifies the commenter or booster. Remote HTML is untrusted.";
3790
+ readonly required: readonly ["id", "kind", "postId", "activityId", "objectId", "actorUrl", "contentHtml", "contentText", "receivedAt", "publishedAt"];
3791
+ readonly properties: {
3792
+ readonly id: {
3793
+ readonly type: "string";
3794
+ readonly format: "uuid";
3795
+ };
3796
+ readonly kind: {
3797
+ readonly type: "string";
3798
+ readonly enum: readonly ["comment", "postBoost"];
3799
+ };
3800
+ readonly postId: {
3801
+ readonly type: "string";
3802
+ readonly format: "uri";
3803
+ };
3804
+ readonly activityId: {
3805
+ readonly type: "string";
3806
+ readonly format: "uri";
3807
+ };
3808
+ readonly objectId: {
3809
+ readonly type: "string";
3810
+ readonly format: "uri";
3811
+ readonly description: "Comment object ID, or the boosted post ID.";
3812
+ };
3813
+ readonly actorUrl: {
3814
+ readonly type: "string";
3815
+ readonly format: "uri";
3816
+ };
3817
+ readonly contentHtml: {
3818
+ readonly type: readonly ["string", "null"];
3819
+ };
3820
+ readonly contentText: {
3821
+ readonly type: readonly ["string", "null"];
3822
+ };
3823
+ readonly publishedAt: {
3824
+ readonly type: readonly ["string", "null"];
3825
+ readonly format: "date-time";
3826
+ };
3827
+ readonly receivedAt: {
3828
+ readonly type: "string";
3829
+ readonly format: "date-time";
3830
+ };
3831
+ };
3832
+ };
3680
3833
  readonly IncomingActivityPage: {
3681
3834
  readonly type: "object";
3682
3835
  readonly required: readonly ["data", "meta"];
@@ -3689,12 +3842,15 @@ export declare const openApiDocument: {
3689
3842
  readonly $ref: "#/components/schemas/IncomingPost";
3690
3843
  }, {
3691
3844
  readonly $ref: "#/components/schemas/IncomingBoost";
3845
+ }, {
3846
+ readonly $ref: "#/components/schemas/IncomingReply";
3692
3847
  }];
3693
3848
  readonly discriminator: {
3694
3849
  readonly propertyName: "kind";
3695
3850
  readonly mapping: {
3696
3851
  readonly post: "#/components/schemas/IncomingPost";
3697
3852
  readonly boost: "#/components/schemas/IncomingBoost";
3853
+ readonly reply: "#/components/schemas/IncomingReply";
3698
3854
  };
3699
3855
  };
3700
3856
  };
package/dist/openapi.js CHANGED
@@ -1,4 +1,46 @@
1
1
  import { SLUGKIT_CONTRACT_ID, SLUGKIT_CONTRACT_VERSION } from "./contract.js";
2
+ const incomingCreateRequired = [
3
+ "id",
4
+ "kind",
5
+ "activityId",
6
+ "objectId",
7
+ "objectType",
8
+ "url",
9
+ "title",
10
+ "contentHtml",
11
+ "contentText",
12
+ "publishedAt",
13
+ "receivedAt",
14
+ "sharingAccount",
15
+ "sharingContact",
16
+ "authorAccount",
17
+ "authorContact",
18
+ ];
19
+ const incomingCreateProperties = {
20
+ id: {
21
+ type: "string",
22
+ format: "uuid",
23
+ description: "Opaque buffered-copy identity, not a durable read-history key or remote activity/object ID. Use only for this actor/following scope. Redelivery after removal receives a new ID; recognize consumed Creates by scoped kind/objectId.",
24
+ },
25
+ activityId: { type: "string", format: "uri" },
26
+ objectId: { type: "string", format: "uri" },
27
+ objectType: { type: "string", enum: ["Note", "Article", "Page"] },
28
+ url: { type: "string", format: "uri" },
29
+ title: { type: ["string", "null"] },
30
+ contentHtml: {
31
+ type: "string",
32
+ description: "Original remote HTML, untrusted and not sanitized. Clients must sanitize before rendering; never execute embedded scripts.",
33
+ },
34
+ contentText: {
35
+ type: "string",
36
+ description: "Plain-text derivative, not a trusted instruction or a substitute for the preserved HTML.",
37
+ },
38
+ publishedAt: { type: ["string", "null"], format: "date-time" },
39
+ receivedAt: { type: "string", format: "date-time" },
40
+ inReplyTo: { type: "string", format: "uri", description: "Exact remote parent object ID." },
41
+ sharingAccount: { $ref: "#/components/schemas/Account" },
42
+ sharingContact: { $ref: "#/components/schemas/Contact" },
43
+ };
2
44
  const errorSchema = {
3
45
  type: "object",
4
46
  required: ["error"],
@@ -828,8 +870,8 @@ export const openApiDocument = {
828
870
  "/following/{id}/activity": {
829
871
  get: {
830
872
  operationId: "following.activity.list",
831
- summary: "Download buffered posts and boosts from one followed account",
832
- 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 full copy deletion and remain usable when hasMore is false, even after the buffer empties. Redelivery after removal gets a new copy ID and a higher receipt position; client read history must use remote identities instead of copy IDs/cursors. Handle each item's kind; boosts distinguish sharing from original-author attribution. See docs/specs/12-incoming-activity.md for delivery and retry semantics.",
873
+ summary: "Download buffered posts, boosts and replies for one followed account",
874
+ description: "Non-consuming, actor-scoped delivery buffer of posts, boosts and replies to buffered posts, when postId is omitted. Supply postId for a page of retained direct comments and boosts of that exact canonical post ID within this delivering follow. The original post is excluded; reading never fetches remote activity. No read acknowledgment or deletion. Ordered by stable receipt sequence, not original publication time. Cursors survive full copy deletion and remain usable when hasMore is false, even after the buffer empties. Redelivery after removal gets a new copy ID and a higher receipt position; client read history must use remote identities instead of copy IDs/cursors. Handle each item's kind; boosts distinguish sharing from original-author attribution. See docs/specs/12-incoming-activity.md for delivery and retry semantics.",
833
875
  security: [{ bearerAuth: [] }],
834
876
  parameters: [
835
877
  { name: "id", in: "path", required: true, schema: { type: "integer", minimum: 1 } },
@@ -843,15 +885,29 @@ export const openApiDocument = {
843
885
  name: "cursor",
844
886
  in: "query",
845
887
  required: false,
846
- description: "Opaque continuation for this actor/following pair. Omit for the oldest available copy. Invalid/cross-scope cursors return 422.",
888
+ description: "Opaque continuation for this actor/following pair and optional postId. Omit for the oldest available copy. Invalid/cross-scope cursors return 422.",
847
889
  schema: { type: "string", minLength: 1, maxLength: 2048 },
848
890
  },
891
+ {
892
+ name: "postId",
893
+ in: "query",
894
+ required: false,
895
+ description: "Canonical objectId of the post, not the local copy ID or display URL.",
896
+ schema: { type: "string", format: "uri", pattern: "^https://" },
897
+ },
849
898
  ],
850
899
  responses: {
851
900
  "200": {
852
- description: "Available copies at query time; concurrent explicit deletion may change later responses. Cache-Control: no-store.",
901
+ description: "IncomingActivityPage by default; PostActivityPage when postId is present. Available copies at query time; concurrent explicit deletion may change later responses. Cache-Control: no-store.",
853
902
  content: {
854
- "application/json": { schema: { $ref: "#/components/schemas/IncomingActivityPage" } },
903
+ "application/json": {
904
+ schema: {
905
+ anyOf: [
906
+ { $ref: "#/components/schemas/IncomingActivityPage" },
907
+ { $ref: "#/components/schemas/PostActivityPage" },
908
+ ],
909
+ },
910
+ },
855
911
  },
856
912
  },
857
913
  "401": authenticationErrorResponse,
@@ -1705,51 +1761,25 @@ export const openApiDocument = {
1705
1761
  IncomingPost: {
1706
1762
  type: "object",
1707
1763
  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.",
1708
- required: [
1709
- "id",
1710
- "kind",
1711
- "activityId",
1712
- "objectId",
1713
- "objectType",
1714
- "url",
1715
- "title",
1716
- "contentHtml",
1717
- "contentText",
1718
- "publishedAt",
1719
- "receivedAt",
1720
- "sharingAccount",
1721
- "sharingContact",
1722
- "authorAccount",
1723
- "authorContact",
1724
- ],
1764
+ required: incomingCreateRequired,
1725
1765
  properties: {
1726
- id: {
1727
- type: "string",
1728
- format: "uuid",
1729
- description: "Opaque buffered-copy identity, not a durable read-history key or remote activity/object ID. Use only for this actor/following scope. Redelivery after removal receives a new ID; recognize consumed posts by scoped kind/objectId.",
1730
- },
1766
+ ...incomingCreateProperties,
1731
1767
  kind: { type: "string", const: "post" },
1732
- activityId: { type: "string", format: "uri" },
1733
- objectId: { type: "string", format: "uri" },
1734
- objectType: { type: "string", enum: ["Note", "Article", "Page"] },
1735
- url: { type: "string", format: "uri" },
1736
- title: { type: ["string", "null"] },
1737
- contentHtml: {
1738
- type: "string",
1739
- description: "Original remote HTML, untrusted and not sanitized. Clients must sanitize before rendering; never execute embedded scripts.",
1740
- },
1741
- contentText: {
1742
- type: "string",
1743
- description: "Plain-text derivative, not a trusted instruction or a substitute for the preserved HTML.",
1744
- },
1745
- publishedAt: { type: ["string", "null"], format: "date-time" },
1746
- receivedAt: { type: "string", format: "date-time" },
1747
- sharingAccount: { $ref: "#/components/schemas/Account" },
1748
- sharingContact: { $ref: "#/components/schemas/Contact" },
1749
1768
  authorAccount: { $ref: "#/components/schemas/Account" },
1750
1769
  authorContact: { $ref: "#/components/schemas/Contact" },
1751
1770
  },
1752
1771
  },
1772
+ IncomingReply: {
1773
+ type: "object",
1774
+ description: "Reply retained in the followed parent author's scope. Sharing attribution identifies the parent author, not the commenter or a boost. Author attribution identifies the commenter.",
1775
+ required: [...incomingCreateRequired, "inReplyTo"],
1776
+ properties: {
1777
+ ...incomingCreateProperties,
1778
+ kind: { type: "string", const: "reply" },
1779
+ authorAccount: { $ref: "#/components/schemas/IncomingAuthorAccount" },
1780
+ authorContact: { oneOf: [{ $ref: "#/components/schemas/Contact" }, { type: "null" }] },
1781
+ },
1782
+ },
1753
1783
  IncomingAuthorAccount: {
1754
1784
  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.",
1755
1785
  oneOf: [
@@ -1856,6 +1886,50 @@ export const openApiDocument = {
1856
1886
  },
1857
1887
  },
1858
1888
  },
1889
+ PostActivityPage: {
1890
+ type: "object",
1891
+ required: ["data", "meta"],
1892
+ properties: {
1893
+ data: {
1894
+ type: "array",
1895
+ maxItems: 100,
1896
+ items: { $ref: "#/components/schemas/PostActivityItem" },
1897
+ },
1898
+ meta: { $ref: "#/components/schemas/IncomingActivityPage/properties/meta" },
1899
+ },
1900
+ },
1901
+ PostActivityItem: {
1902
+ type: "object",
1903
+ description: "Only returned for postId queries. id is the removable copy in the requested follow; actorUrl identifies the commenter or booster. Remote HTML is untrusted.",
1904
+ required: [
1905
+ "id",
1906
+ "kind",
1907
+ "postId",
1908
+ "activityId",
1909
+ "objectId",
1910
+ "actorUrl",
1911
+ "contentHtml",
1912
+ "contentText",
1913
+ "receivedAt",
1914
+ "publishedAt",
1915
+ ],
1916
+ properties: {
1917
+ id: { type: "string", format: "uuid" },
1918
+ kind: { type: "string", enum: ["comment", "postBoost"] },
1919
+ postId: { type: "string", format: "uri" },
1920
+ activityId: { type: "string", format: "uri" },
1921
+ objectId: {
1922
+ type: "string",
1923
+ format: "uri",
1924
+ description: "Comment object ID, or the boosted post ID.",
1925
+ },
1926
+ actorUrl: { type: "string", format: "uri" },
1927
+ contentHtml: { type: ["string", "null"] },
1928
+ contentText: { type: ["string", "null"] },
1929
+ publishedAt: { type: ["string", "null"], format: "date-time" },
1930
+ receivedAt: { type: "string", format: "date-time" },
1931
+ },
1932
+ },
1859
1933
  IncomingActivityPage: {
1860
1934
  type: "object",
1861
1935
  required: ["data", "meta"],
@@ -1867,12 +1941,14 @@ export const openApiDocument = {
1867
1941
  oneOf: [
1868
1942
  { $ref: "#/components/schemas/IncomingPost" },
1869
1943
  { $ref: "#/components/schemas/IncomingBoost" },
1944
+ { $ref: "#/components/schemas/IncomingReply" },
1870
1945
  ],
1871
1946
  discriminator: {
1872
1947
  propertyName: "kind",
1873
1948
  mapping: {
1874
1949
  post: "#/components/schemas/IncomingPost",
1875
1950
  boost: "#/components/schemas/IncomingBoost",
1951
+ reply: "#/components/schemas/IncomingReply",
1876
1952
  },
1877
1953
  },
1878
1954
  },
package/dist/openapi.json CHANGED
@@ -2,11 +2,11 @@
2
2
  "openapi": "3.1.0",
3
3
  "x-slugkit-contract": {
4
4
  "id": "slugkit-management-api",
5
- "version": "3.0.0"
5
+ "version": "4.1.0"
6
6
  },
7
7
  "info": {
8
8
  "title": "Slugkit API",
9
- "version": "3.0.0"
9
+ "version": "4.1.0"
10
10
  },
11
11
  "servers": [
12
12
  {
@@ -1714,8 +1714,8 @@
1714
1714
  "/following/{id}/activity": {
1715
1715
  "get": {
1716
1716
  "operationId": "following.activity.list",
1717
- "summary": "Download buffered posts and boosts from one followed account",
1718
- "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 full copy deletion and remain usable when hasMore is false, even after the buffer empties. Redelivery after removal gets a new copy ID and a higher receipt position; client read history must use remote identities instead of copy IDs/cursors. Handle each item's kind; boosts distinguish sharing from original-author attribution. See docs/specs/12-incoming-activity.md for delivery and retry semantics.",
1717
+ "summary": "Download buffered posts, boosts and replies for one followed account",
1718
+ "description": "Non-consuming, actor-scoped delivery buffer of posts, boosts and replies to buffered posts, when postId is omitted. Supply postId for a page of retained direct comments and boosts of that exact canonical post ID within this delivering follow. The original post is excluded; reading never fetches remote activity. No read acknowledgment or deletion. Ordered by stable receipt sequence, not original publication time. Cursors survive full copy deletion and remain usable when hasMore is false, even after the buffer empties. Redelivery after removal gets a new copy ID and a higher receipt position; client read history must use remote identities instead of copy IDs/cursors. Handle each item's kind; boosts distinguish sharing from original-author attribution. See docs/specs/12-incoming-activity.md for delivery and retry semantics.",
1719
1719
  "security": [
1720
1720
  {
1721
1721
  "bearerAuth": []
@@ -1746,21 +1746,39 @@
1746
1746
  "name": "cursor",
1747
1747
  "in": "query",
1748
1748
  "required": false,
1749
- "description": "Opaque continuation for this actor/following pair. Omit for the oldest available copy. Invalid/cross-scope cursors return 422.",
1749
+ "description": "Opaque continuation for this actor/following pair and optional postId. Omit for the oldest available copy. Invalid/cross-scope cursors return 422.",
1750
1750
  "schema": {
1751
1751
  "type": "string",
1752
1752
  "minLength": 1,
1753
1753
  "maxLength": 2048
1754
1754
  }
1755
+ },
1756
+ {
1757
+ "name": "postId",
1758
+ "in": "query",
1759
+ "required": false,
1760
+ "description": "Canonical objectId of the post, not the local copy ID or display URL.",
1761
+ "schema": {
1762
+ "type": "string",
1763
+ "format": "uri",
1764
+ "pattern": "^https://"
1765
+ }
1755
1766
  }
1756
1767
  ],
1757
1768
  "responses": {
1758
1769
  "200": {
1759
- "description": "Available copies at query time; concurrent explicit deletion may change later responses. Cache-Control: no-store.",
1770
+ "description": "IncomingActivityPage by default; PostActivityPage when postId is present. Available copies at query time; concurrent explicit deletion may change later responses. Cache-Control: no-store.",
1760
1771
  "content": {
1761
1772
  "application/json": {
1762
1773
  "schema": {
1763
- "$ref": "#/components/schemas/IncomingActivityPage"
1774
+ "anyOf": [
1775
+ {
1776
+ "$ref": "#/components/schemas/IncomingActivityPage"
1777
+ },
1778
+ {
1779
+ "$ref": "#/components/schemas/PostActivityPage"
1780
+ }
1781
+ ]
1764
1782
  }
1765
1783
  }
1766
1784
  }
@@ -3012,7 +3030,7 @@
3012
3030
  },
3013
3031
  "version": {
3014
3032
  "type": "string",
3015
- "const": "3.0.0"
3033
+ "const": "4.1.0"
3016
3034
  }
3017
3035
  }
3018
3036
  }
@@ -3979,12 +3997,103 @@
3979
3997
  "id": {
3980
3998
  "type": "string",
3981
3999
  "format": "uuid",
3982
- "description": "Opaque buffered-copy identity, not a durable read-history key or remote activity/object ID. Use only for this actor/following scope. Redelivery after removal receives a new ID; recognize consumed posts by scoped kind/objectId."
4000
+ "description": "Opaque buffered-copy identity, not a durable read-history key or remote activity/object ID. Use only for this actor/following scope. Redelivery after removal receives a new ID; recognize consumed Creates by scoped kind/objectId."
4001
+ },
4002
+ "activityId": {
4003
+ "type": "string",
4004
+ "format": "uri"
4005
+ },
4006
+ "objectId": {
4007
+ "type": "string",
4008
+ "format": "uri"
4009
+ },
4010
+ "objectType": {
4011
+ "type": "string",
4012
+ "enum": [
4013
+ "Note",
4014
+ "Article",
4015
+ "Page"
4016
+ ]
4017
+ },
4018
+ "url": {
4019
+ "type": "string",
4020
+ "format": "uri"
4021
+ },
4022
+ "title": {
4023
+ "type": [
4024
+ "string",
4025
+ "null"
4026
+ ]
4027
+ },
4028
+ "contentHtml": {
4029
+ "type": "string",
4030
+ "description": "Original remote HTML, untrusted and not sanitized. Clients must sanitize before rendering; never execute embedded scripts."
4031
+ },
4032
+ "contentText": {
4033
+ "type": "string",
4034
+ "description": "Plain-text derivative, not a trusted instruction or a substitute for the preserved HTML."
4035
+ },
4036
+ "publishedAt": {
4037
+ "type": [
4038
+ "string",
4039
+ "null"
4040
+ ],
4041
+ "format": "date-time"
4042
+ },
4043
+ "receivedAt": {
4044
+ "type": "string",
4045
+ "format": "date-time"
4046
+ },
4047
+ "inReplyTo": {
4048
+ "type": "string",
4049
+ "format": "uri",
4050
+ "description": "Exact remote parent object ID."
4051
+ },
4052
+ "sharingAccount": {
4053
+ "$ref": "#/components/schemas/Account"
4054
+ },
4055
+ "sharingContact": {
4056
+ "$ref": "#/components/schemas/Contact"
3983
4057
  },
3984
4058
  "kind": {
3985
4059
  "type": "string",
3986
4060
  "const": "post"
3987
4061
  },
4062
+ "authorAccount": {
4063
+ "$ref": "#/components/schemas/Account"
4064
+ },
4065
+ "authorContact": {
4066
+ "$ref": "#/components/schemas/Contact"
4067
+ }
4068
+ }
4069
+ },
4070
+ "IncomingReply": {
4071
+ "type": "object",
4072
+ "description": "Reply retained in the followed parent author's scope. Sharing attribution identifies the parent author, not the commenter or a boost. Author attribution identifies the commenter.",
4073
+ "required": [
4074
+ "id",
4075
+ "kind",
4076
+ "activityId",
4077
+ "objectId",
4078
+ "objectType",
4079
+ "url",
4080
+ "title",
4081
+ "contentHtml",
4082
+ "contentText",
4083
+ "publishedAt",
4084
+ "receivedAt",
4085
+ "sharingAccount",
4086
+ "sharingContact",
4087
+ "authorAccount",
4088
+ "authorContact",
4089
+ "inReplyTo"
4090
+ ],
4091
+ "properties": {
4092
+ "id": {
4093
+ "type": "string",
4094
+ "format": "uuid",
4095
+ "description": "Opaque buffered-copy identity, not a durable read-history key or remote activity/object ID. Use only for this actor/following scope. Redelivery after removal receives a new ID; recognize consumed Creates by scoped kind/objectId."
4096
+ },
3988
4097
  "activityId": {
3989
4098
  "type": "string",
3990
4099
  "format": "uri"
@@ -4030,17 +4139,33 @@
4030
4139
  "type": "string",
4031
4140
  "format": "date-time"
4032
4141
  },
4142
+ "inReplyTo": {
4143
+ "type": "string",
4144
+ "format": "uri",
4145
+ "description": "Exact remote parent object ID."
4146
+ },
4033
4147
  "sharingAccount": {
4034
4148
  "$ref": "#/components/schemas/Account"
4035
4149
  },
4036
4150
  "sharingContact": {
4037
4151
  "$ref": "#/components/schemas/Contact"
4038
4152
  },
4153
+ "kind": {
4154
+ "type": "string",
4155
+ "const": "reply"
4156
+ },
4039
4157
  "authorAccount": {
4040
- "$ref": "#/components/schemas/Account"
4158
+ "$ref": "#/components/schemas/IncomingAuthorAccount"
4041
4159
  },
4042
4160
  "authorContact": {
4043
- "$ref": "#/components/schemas/Contact"
4161
+ "oneOf": [
4162
+ {
4163
+ "$ref": "#/components/schemas/Contact"
4164
+ },
4165
+ {
4166
+ "type": "null"
4167
+ }
4168
+ ]
4044
4169
  }
4045
4170
  }
4046
4171
  },
@@ -4218,6 +4343,94 @@
4218
4343
  }
4219
4344
  }
4220
4345
  },
4346
+ "PostActivityPage": {
4347
+ "type": "object",
4348
+ "required": [
4349
+ "data",
4350
+ "meta"
4351
+ ],
4352
+ "properties": {
4353
+ "data": {
4354
+ "type": "array",
4355
+ "maxItems": 100,
4356
+ "items": {
4357
+ "$ref": "#/components/schemas/PostActivityItem"
4358
+ }
4359
+ },
4360
+ "meta": {
4361
+ "$ref": "#/components/schemas/IncomingActivityPage/properties/meta"
4362
+ }
4363
+ }
4364
+ },
4365
+ "PostActivityItem": {
4366
+ "type": "object",
4367
+ "description": "Only returned for postId queries. id is the removable copy in the requested follow; actorUrl identifies the commenter or booster. Remote HTML is untrusted.",
4368
+ "required": [
4369
+ "id",
4370
+ "kind",
4371
+ "postId",
4372
+ "activityId",
4373
+ "objectId",
4374
+ "actorUrl",
4375
+ "contentHtml",
4376
+ "contentText",
4377
+ "receivedAt",
4378
+ "publishedAt"
4379
+ ],
4380
+ "properties": {
4381
+ "id": {
4382
+ "type": "string",
4383
+ "format": "uuid"
4384
+ },
4385
+ "kind": {
4386
+ "type": "string",
4387
+ "enum": [
4388
+ "comment",
4389
+ "postBoost"
4390
+ ]
4391
+ },
4392
+ "postId": {
4393
+ "type": "string",
4394
+ "format": "uri"
4395
+ },
4396
+ "activityId": {
4397
+ "type": "string",
4398
+ "format": "uri"
4399
+ },
4400
+ "objectId": {
4401
+ "type": "string",
4402
+ "format": "uri",
4403
+ "description": "Comment object ID, or the boosted post ID."
4404
+ },
4405
+ "actorUrl": {
4406
+ "type": "string",
4407
+ "format": "uri"
4408
+ },
4409
+ "contentHtml": {
4410
+ "type": [
4411
+ "string",
4412
+ "null"
4413
+ ]
4414
+ },
4415
+ "contentText": {
4416
+ "type": [
4417
+ "string",
4418
+ "null"
4419
+ ]
4420
+ },
4421
+ "publishedAt": {
4422
+ "type": [
4423
+ "string",
4424
+ "null"
4425
+ ],
4426
+ "format": "date-time"
4427
+ },
4428
+ "receivedAt": {
4429
+ "type": "string",
4430
+ "format": "date-time"
4431
+ }
4432
+ }
4433
+ },
4221
4434
  "IncomingActivityPage": {
4222
4435
  "type": "object",
4223
4436
  "required": [
@@ -4235,13 +4448,17 @@
4235
4448
  },
4236
4449
  {
4237
4450
  "$ref": "#/components/schemas/IncomingBoost"
4451
+ },
4452
+ {
4453
+ "$ref": "#/components/schemas/IncomingReply"
4238
4454
  }
4239
4455
  ],
4240
4456
  "discriminator": {
4241
4457
  "propertyName": "kind",
4242
4458
  "mapping": {
4243
4459
  "post": "#/components/schemas/IncomingPost",
4244
- "boost": "#/components/schemas/IncomingBoost"
4460
+ "boost": "#/components/schemas/IncomingBoost",
4461
+ "reply": "#/components/schemas/IncomingReply"
4245
4462
  }
4246
4463
  }
4247
4464
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@evcraddock/slug-api",
3
- "version": "2.0.0",
3
+ "version": "3.0.0",
4
4
  "description": "Reusable Hono helpers for Slugkit-compatible management APIs.",
5
5
  "license": "MIT",
6
6
  "private": false,