@estiva-app/conversation 0.1.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.
Files changed (54) hide show
  1. package/CHANGELOG.md +37 -0
  2. package/LICENSE +21 -0
  3. package/README.md +42 -0
  4. package/dist/builders.d.ts +73 -0
  5. package/dist/builders.d.ts.map +1 -0
  6. package/dist/builders.js +110 -0
  7. package/dist/builders.js.map +1 -0
  8. package/dist/decorations.d.ts +88 -0
  9. package/dist/decorations.d.ts.map +1 -0
  10. package/dist/decorations.js +133 -0
  11. package/dist/decorations.js.map +1 -0
  12. package/dist/drafts.d.ts +74 -0
  13. package/dist/drafts.d.ts.map +1 -0
  14. package/dist/drafts.js +111 -0
  15. package/dist/drafts.js.map +1 -0
  16. package/dist/edits.d.ts +76 -0
  17. package/dist/edits.d.ts.map +1 -0
  18. package/dist/edits.js +123 -0
  19. package/dist/edits.js.map +1 -0
  20. package/dist/index.d.ts +25 -0
  21. package/dist/index.d.ts.map +1 -0
  22. package/dist/index.js +25 -0
  23. package/dist/index.js.map +1 -0
  24. package/dist/kinds.d.ts +17 -0
  25. package/dist/kinds.d.ts.map +1 -0
  26. package/dist/kinds.js +22 -0
  27. package/dist/kinds.js.map +1 -0
  28. package/dist/order.d.ts +24 -0
  29. package/dist/order.d.ts.map +1 -0
  30. package/dist/order.js +21 -0
  31. package/dist/order.js.map +1 -0
  32. package/dist/reactions.d.ts +93 -0
  33. package/dist/reactions.d.ts.map +1 -0
  34. package/dist/reactions.js +99 -0
  35. package/dist/reactions.js.map +1 -0
  36. package/dist/strength.d.ts +104 -0
  37. package/dist/strength.d.ts.map +1 -0
  38. package/dist/strength.js +166 -0
  39. package/dist/strength.js.map +1 -0
  40. package/dist/threads.d.ts +54 -0
  41. package/dist/threads.d.ts.map +1 -0
  42. package/dist/threads.js +70 -0
  43. package/dist/threads.js.map +1 -0
  44. package/package.json +56 -0
  45. package/src/builders.ts +133 -0
  46. package/src/decorations.ts +187 -0
  47. package/src/drafts.ts +135 -0
  48. package/src/edits.ts +139 -0
  49. package/src/index.ts +74 -0
  50. package/src/kinds.ts +24 -0
  51. package/src/order.ts +38 -0
  52. package/src/reactions.ts +151 -0
  53. package/src/strength.ts +170 -0
  54. package/src/threads.ts +104 -0
package/src/kinds.ts ADDED
@@ -0,0 +1,24 @@
1
+ /**
2
+ * The kinds a conversation is made of. Numbers from the protocol, named here
3
+ * so every module reads the same one.
4
+ */
5
+ import { KIND } from '@estiva-app/protocol'
6
+
7
+ /** A message in a channel — chat (SPEC §6.4, §6.7). */
8
+ export const KIND_MESSAGE = KIND.STREAM_MESSAGE
9
+ /** A NIP-22 comment on an object, and a reply to one (§6.4). */
10
+ export const KIND_COMMENT = KIND.COMMENT
11
+ /** An edit of a message or comment (§6.8). */
12
+ export const KIND_EDIT = KIND.MESSAGE_EDIT
13
+ /** A NIP-25 reaction (§6.6). */
14
+ export const KIND_REACTION = KIND.REACTION
15
+ /** A NIP-09 deletion request (§6.5). */
16
+ export const KIND_DELETION = KIND.DELETION
17
+ /** An assertion; with `t=resolution` it resolves or reopens a comment (PEEK-128). */
18
+ export const KIND_ASSERTION = KIND.ASSERTION
19
+
20
+ /** Whether the event is a message or a comment — what a conversation lists. */
21
+ export const isConversationKind = (kind: number): boolean => kind === KIND_MESSAGE || kind === KIND_COMMENT
22
+
23
+ /** A 64-hex event id. */
24
+ export const isEventId = (value: unknown): value is string => typeof value === 'string' && /^[0-9a-fA-F]{64}$/.test(value)
package/src/order.ts ADDED
@@ -0,0 +1,38 @@
1
+ /**
2
+ * The one ordering — SPEC §6.3, with §6.2's `ts` rule.
3
+ *
4
+ * Ordering, most significant first: `ts` (when trusted), then `created_at`,
5
+ * then event `id`. Edits (§6.8) fold by it on purpose, because a second
6
+ * ordering rule in the same protocol is a second thing to get wrong.
7
+ *
8
+ * **`ts` is trusted only when `floor(ts / 1000) == created_at`, exactly**
9
+ * (§6.2, clarified 2026-09-29, CON-5). Peek's edit fold and interop's change
10
+ * and edit folds accepted ±1 s; that lets a `ts` claim the neighbouring second,
11
+ * which is the one thing the rule exists to prevent. Every writer floors, and
12
+ * all 3,470 events carrying `ts` on production agreed exactly, so the strict
13
+ * reading changes no fold that exists.
14
+ */
15
+ import type { SignedEvent } from '@estiva-app/protocol'
16
+
17
+ type Ordered = Pick<SignedEvent, 'id' | 'created_at' | 'tags'>
18
+
19
+ /** The event's `ts` in epoch milliseconds when §6.2 lets a reader trust it, else undefined. */
20
+ export function trustedTs(event: Pick<SignedEvent, 'created_at' | 'tags'>): number | undefined {
21
+ const value = event.tags.find((t) => t[0] === 'ts')?.[1]
22
+ if (value === undefined || !/^\d+$/.test(value)) return undefined
23
+ const ms = Number(value)
24
+ return Number.isSafeInteger(ms) && Math.floor(ms / 1000) === event.created_at ? ms : undefined
25
+ }
26
+
27
+ /** Epoch milliseconds to order by: the trusted `ts`, else `created_at` as milliseconds. */
28
+ export function orderingMs(event: Pick<SignedEvent, 'created_at' | 'tags'>): number {
29
+ return trustedTs(event) ?? event.created_at * 1000
30
+ }
31
+
32
+ /** Oldest first by §6.3: `ts` when trusted, then `created_at`, then the lower id. */
33
+ export function byOrder(a: Ordered, b: Ordered): number {
34
+ const at = orderingMs(a)
35
+ const bt = orderingMs(b)
36
+ if (at !== bt) return at - bt
37
+ return a.id < b.id ? -1 : a.id > b.id ? 1 : 0
38
+ }
@@ -0,0 +1,151 @@
1
+ /**
2
+ * Reactions — SPEC §6.6.
3
+ *
4
+ * A reaction is a NIP-25 `kind:7` naming its target by `e`. **It carries no
5
+ * `h`**, so a channel read never returns one: reactions are fetched addressed
6
+ * by target, which forces a horizon every reader must share.
7
+ *
8
+ * Two apps must agree on a **count**, so what counts is specified (decided
9
+ * 2026-09-29, CON-5):
10
+ *
11
+ * - **Target**: the **last** `e` whose value is 64 hex, as NIP-25 says — the
12
+ * one the relay files the reaction under (`handlers/ingest.rs`).
13
+ * - **Emoji**: the content as stored, **not trimmed**; an empty content is
14
+ * `+`, NIP-25's "like".
15
+ * - **Count**: one per `(target, pubkey, emoji)`. The relay refuses an active
16
+ * duplicate; a reader still deduplicates, because a copy need not.
17
+ * - **Retraction** is a `kind:5` on the reaction, and the relay stops
18
+ * returning it, so a reader re-reads and does not reconcile.
19
+ * - **Order** is presentation. This keeps first-reaction order; an app MAY
20
+ * sort by count, and two apps that differ there disagree about nothing.
21
+ */
22
+ import type { SignedEvent } from '@estiva-app/protocol'
23
+ import { isEventId, KIND_REACTION } from './kinds.js'
24
+ import { byOrder } from './order.js'
25
+
26
+ /**
27
+ * How many targets a reaction read asks about — SPEC §6.6, decided by CON-1.
28
+ * The value is the specification's; two apps with different N disagree about
29
+ * a count, legitimately and unfixably.
30
+ */
31
+ export const REACTION_HORIZON = 100
32
+
33
+ /**
34
+ * The emoji a person can pick, and what each one means — the same five in
35
+ * both apps, in the same order, because a reaction you can read is one you
36
+ * should be able to answer. The name is the tooltip and the accessible name.
37
+ */
38
+ export const REACTION_EMOJI: readonly { emoji: string; name: string }[] = [
39
+ { emoji: '👍', name: 'Makes sense' },
40
+ { emoji: '💯', name: 'Agree' },
41
+ { emoji: '🙏', name: 'Thank you' },
42
+ { emoji: '🚀', name: "Let's go!" },
43
+ { emoji: '🎉', name: 'Congrats' },
44
+ ]
45
+
46
+ /** The event a `kind:7` reacts to: the **last** 64-hex `e`, lowercased. */
47
+ export function reactionTargetOf(event: Pick<SignedEvent, 'tags'>): string | undefined {
48
+ for (let i = event.tags.length - 1; i >= 0; i--) {
49
+ const t = event.tags[i]
50
+ if (t[0] === 'e' && isEventId(t[1])) return t[1].toLowerCase()
51
+ }
52
+ return undefined
53
+ }
54
+
55
+ /** The emoji a `kind:7` carries: its content untrimmed, `+` when empty. */
56
+ export function reactionEmojiOf(event: Pick<SignedEvent, 'content'>): string {
57
+ return event.content === '' ? '+' : event.content
58
+ }
59
+
60
+ /** Which targets a reaction read asks about, and how many it leaves out. */
61
+ export interface ReactionHorizon {
62
+ /** The ids to ask about, newest first. */
63
+ asked: string[]
64
+ /** How many were left out — what §6.6 makes reporting a MUST. */
65
+ omitted: number
66
+ }
67
+
68
+ /**
69
+ * The horizon applied: **the newest {@link REACTION_HORIZON} targets by
70
+ * `created_at`, ties broken on the higher id**, in one budget across every id
71
+ * space the caller mixes (roots and replies alike). `at` is the target's
72
+ * `created_at` in seconds; a repeated id counts once.
73
+ */
74
+ export function reactionHorizon(targets: readonly { id: string; at: number }[], limit = REACTION_HORIZON): ReactionHorizon {
75
+ const unique = new Map<string, number>()
76
+ for (const t of targets) if (!unique.has(t.id)) unique.set(t.id, t.at)
77
+ const newestFirst = [...unique].sort((a, b) => b[1] - a[1] || (a[0] > b[0] ? -1 : a[0] < b[0] ? 1 : 0))
78
+ return { asked: newestFirst.slice(0, limit).map(([id]) => id), omitted: Math.max(0, newestFirst.length - limit) }
79
+ }
80
+
81
+ /** One reaction event, read. */
82
+ export interface ReactionEvent {
83
+ id: string
84
+ target: string
85
+ emoji: string
86
+ by: string
87
+ at: number
88
+ }
89
+
90
+ /**
91
+ * Every `kind:7` in `events`, read by §6.6 and deduplicated per
92
+ * `(target, pubkey, emoji)` — the earliest wins, so a retraction names it.
93
+ * Oldest first by §6.3. A reaction with no 64-hex `e` is nobody's.
94
+ */
95
+ export function reactionEventsOf(events: readonly SignedEvent[]): ReactionEvent[] {
96
+ const out: ReactionEvent[] = []
97
+ const counted = new Set<string>()
98
+ const seen = new Set<string>()
99
+ for (const event of [...events].sort(byOrder)) {
100
+ if (event.kind !== KIND_REACTION || seen.has(event.id)) continue
101
+ seen.add(event.id)
102
+ const target = reactionTargetOf(event)
103
+ if (!target) continue
104
+ const emoji = reactionEmojiOf(event)
105
+ const key = JSON.stringify([target, event.pubkey, emoji])
106
+ if (counted.has(key)) continue
107
+ counted.add(key)
108
+ out.push({ id: event.id, target, emoji, by: event.pubkey, at: event.created_at })
109
+ }
110
+ return out
111
+ }
112
+
113
+ /** One emoji on one target, and who put it there. */
114
+ export interface Reaction {
115
+ emoji: string
116
+ /** Distinct reactors — one per pubkey. */
117
+ count: number
118
+ /** Reactor pubkeys, in the order they reacted. */
119
+ by: string[]
120
+ /**
121
+ * The viewer's own reaction event id, when they are among `by` — what a
122
+ * retraction (`kind:5` on the reaction) names.
123
+ */
124
+ mine?: string
125
+ }
126
+
127
+ /**
128
+ * Fold `kind:7` events into per-target counts (C13): target id → one entry per
129
+ * emoji, in first-reaction order. `viewer` fills `mine`.
130
+ */
131
+ export function foldReactions(events: readonly SignedEvent[], viewer?: string): Record<string, Reaction[]> {
132
+ return groupReactions(reactionEventsOf(events), viewer)
133
+ }
134
+
135
+ /** {@link foldReactions} over reactions already read by {@link reactionEventsOf}. */
136
+ export function groupReactions(reactions: readonly ReactionEvent[], viewer?: string): Record<string, Reaction[]> {
137
+ const out: Record<string, Reaction[]> = {}
138
+ for (const r of reactions) {
139
+ const list = (out[r.target] ??= [])
140
+ let entry = list.find((e) => e.emoji === r.emoji)
141
+ if (!entry) {
142
+ entry = { emoji: r.emoji, count: 0, by: [] }
143
+ list.push(entry)
144
+ }
145
+ if (entry.by.includes(r.by)) continue
146
+ entry.by.push(r.by)
147
+ entry.count += 1
148
+ if (viewer !== undefined && r.by === viewer) entry.mine = r.id
149
+ }
150
+ return out
151
+ }
@@ -0,0 +1,170 @@
1
+ /**
2
+ * Which object a conversation is about, and how strongly — SPEC §6.4.
3
+ *
4
+ * A thread attaches to every object anyone in it referenced, and that is only
5
+ * defensible because attachment has **two strengths** an app MUST present
6
+ * apart:
7
+ *
8
+ * | on the thread's root | strength |
9
+ * | --- | --- |
10
+ * | a `kind:1111`'s `A` | **comment**: NIP-22's root object |
11
+ * | a `kind:1111`'s `a` that is not its `A` | **mention**: the index of an address the body names |
12
+ * | a `kind:9`'s `a`, or a `nostr:naddr…` in any body | **mention** |
13
+ * | any tag on a reply | nothing: only the root decides |
14
+ *
15
+ * A `kind:1111` with no `A` is malformed; a reader takes **every** `a` it
16
+ * carries as an `A` rather than dropping the thread (clarified 2026-09-29).
17
+ *
18
+ * **A `kind:9` is not a comment** (SPEC §6.4, corrected 2026-09-30, CON-20):
19
+ * every comment-shaped `kind:9` on production was republished as a
20
+ * `kind:1111`, so a channel's chat lists under no object whatever `a` it
21
+ * carries (C10). Ship's `anchorIndex` and interop's `isCommentOn` read a
22
+ * `kind:9` whose `a` the body does not name as a pre-REW-10 comment; that row
23
+ * is gone, except for an app whose manifest still declares such a history
24
+ * (`emits.alsoRead`, §7.3) — see {@link isCommentOn}'s `declaredKinds`.
25
+ *
26
+ * **A reply is never a root** (added 2026-09-29, CON-5). An event carrying a
27
+ * reply `e` — a `kind:9` with any `e`, a `kind:1111` with a lowercase `e` that
28
+ * differs from its `E` — is not a comment of its own, whatever `a` it carries.
29
+ */
30
+ import { decodeNaddr, decodeNpub, findNaddrs, findNostrUris, pointerToAddress, type NostrTag, type SignedEvent } from '@estiva-app/protocol'
31
+ import { KIND_COMMENT } from './kinds.js'
32
+
33
+ type Tagged = Pick<SignedEvent, 'kind' | 'tags'>
34
+ type Readable = Pick<SignedEvent, 'kind' | 'tags' | 'content'>
35
+
36
+ /** Presented as the object's own discussion, or as *Mentioned in*. */
37
+ export type Strength = 'comment' | 'mention'
38
+
39
+ const values = (event: Pick<SignedEvent, 'tags'>, name: string): string[] =>
40
+ event.tags.filter((t) => t[0] === name && typeof t[1] === 'string' && t[1] !== '').map((t) => t[1])
41
+
42
+ /** The addresses a body names by `nostr:naddr…`. A pointer that will not decode is prose. */
43
+ export function namedInBody(body: string): Set<string> {
44
+ const addresses = new Set<string>()
45
+ for (const naddr of findNaddrs(body)) {
46
+ try {
47
+ addresses.add(pointerToAddress(decodeNaddr(naddr)))
48
+ } catch {
49
+ // A malformed pointer is prose.
50
+ }
51
+ }
52
+ return addresses
53
+ }
54
+
55
+ /**
56
+ * Whether the event answers another: a `kind:9` with any `e`, or a
57
+ * `kind:1111` with a lowercase `e` that differs from its `E`.
58
+ *
59
+ * A top-level comment on an *event* root carries `E` and `e` naming the same
60
+ * event and is not a reply. On an address root it carries no `e` at all.
61
+ */
62
+ export function isReply(event: Pick<SignedEvent, 'kind' | 'tags'>): boolean {
63
+ // A NIP-10 `mention`-marked `e` quotes an event; it answers nothing.
64
+ const es = event.tags.filter((t) => t[0] === 'e' && typeof t[1] === 'string' && t[1] !== '' && t[3] !== 'mention').map((t) => t[1])
65
+ if (es.length === 0) return false
66
+ if (event.kind !== KIND_COMMENT) return true
67
+ const root = values(event, 'E')[0]
68
+ return es.some((e) => e !== root)
69
+ }
70
+
71
+ /**
72
+ * The addresses the event's thread is **about** — its `A` tags, or every `a`
73
+ * when it carries no `A`. Only a `kind:1111` has any.
74
+ *
75
+ * On a reply this is the thread's object, not the reply's own strength: a
76
+ * reply copies the comment's `A` (§6.4 *Replies*). {@link isCommentOn} is the
77
+ * test for whether the event itself lists as a comment.
78
+ */
79
+ export function anchorsOf(event: Tagged): string[] {
80
+ if (event.kind !== KIND_COMMENT) return []
81
+ const roots = values(event, 'A')
82
+ return [...new Set(roots.length > 0 ? roots : values(event, 'a'))]
83
+ }
84
+
85
+ /**
86
+ * Is the event a **comment** on the address: a root whose thread is about it
87
+ * (C10, C11).
88
+ *
89
+ * `declaredKinds` is the object's owner's comment kinds, as its manifest
90
+ * declares them (§7.3: `emits.kind` and `emits.alsoRead`); the default is
91
+ * NIP-22's alone. A kind other than `1111` is a comment only when its owner
92
+ * declares it — the history §7.3 says an app declares when it has *not*
93
+ * migrated it — and is then read the way such a comment was written: by an
94
+ * `a` its body does not name. Undeclared, a `kind:9` is chat and lists under
95
+ * no object whatever `a` it carries (§6.4, CON-20).
96
+ */
97
+ export function isCommentOn(event: Readable, address: string, declaredKinds: readonly number[] = [KIND_COMMENT]): boolean {
98
+ if (isReply(event)) return false
99
+ if (event.kind === KIND_COMMENT) return anchorsOf(event).includes(address)
100
+ if (!declaredKinds.includes(event.kind)) return false
101
+ return event.tags.some((t) => t[0] === 'a' && t[1] === address) && !namedInBody(event.content).has(address)
102
+ }
103
+
104
+ /** Does the event name the address at all — any `a` or `A`, or a `nostr:naddr…` in its body. */
105
+ export function referencesAddress(event: Readable, address: string): boolean {
106
+ if (event.tags.some((t) => (t[0] === 'a' || t[0] === 'A') && t[1] === address)) return true
107
+ return namedInBody(event.content).has(address)
108
+ }
109
+
110
+ /**
111
+ * How one event attaches to the address on its own: a comment, a mention, or
112
+ * nothing. A reply is always nothing (C11): its tags name its parent or repeat
113
+ * the root's, and only the root decides.
114
+ *
115
+ * For a whole thread — which attaches as a mention when any message in it
116
+ * names the address — see {@link threadStrength}.
117
+ */
118
+ export function strengthOn(event: Readable, address: string): Strength | null {
119
+ if (isReply(event)) return null
120
+ if (isCommentOn(event, address)) return 'comment'
121
+ return referencesAddress(event, address) ? 'mention' : null
122
+ }
123
+
124
+ /**
125
+ * How a thread attaches to the address: a **comment** when its root is one,
126
+ * else a **mention** when any message in it — the root or a reply — names the
127
+ * address, else nothing.
128
+ *
129
+ * Thread-wide on purpose (§6.4): a discussion that names an object halfway
130
+ * through is from then on about that object, and the earlier messages are the
131
+ * context somebody needs. Pass `root` undefined when the root is outside the
132
+ * read; the thread can then only be a mention, since only the root decides
133
+ * the comment.
134
+ */
135
+ export function threadStrength(root: Readable | undefined, replies: readonly Readable[], address: string): Strength | null {
136
+ if (root && isCommentOn(root, address)) return 'comment'
137
+ const all = root ? [root, ...replies] : replies
138
+ return all.some((event) => referencesAddress(event, address)) ? 'mention' : null
139
+ }
140
+
141
+ /**
142
+ * The `a` tags a body earns: every address it names by `nostr:naddr…`, except
143
+ * `own` (the object the event is already a comment on, which is its `A`).
144
+ *
145
+ * §6.4: a writer MUST NOT put an address in a `kind:1111`'s `a` that the body
146
+ * does not name, unless it is the `A` — which is what keeps the mention row
147
+ * readable without decoding the body.
148
+ */
149
+ export function referenceTagsFor(body: string, own = ''): NostrTag[] {
150
+ const addresses = namedInBody(body)
151
+ addresses.delete(own)
152
+ return [...addresses].map((a) => ['a', a])
153
+ }
154
+
155
+ /** The most `p` tags a message carries — Buzz's cap, and `buildMessage`'s. */
156
+ export const MAX_MENTIONED_PEOPLE = 50
157
+
158
+ /** The people a body mentions by `nostr:npub…`, as `p` tags, capped at {@link MAX_MENTIONED_PEOPLE}. */
159
+ export function mentionTagsFor(body: string): NostrTag[] {
160
+ const pubkeys = new Set<string>()
161
+ for (const uri of findNostrUris(body)) {
162
+ if (!/^nostr:npub1/i.test(uri)) continue
163
+ try {
164
+ pubkeys.add(decodeNpub(uri))
165
+ } catch {
166
+ // A malformed key is prose.
167
+ }
168
+ }
169
+ return [...pubkeys].slice(0, MAX_MENTIONED_PEOPLE).map((p) => ['p', p])
170
+ }
package/src/threads.ts ADDED
@@ -0,0 +1,104 @@
1
+ /**
2
+ * Threading — SPEC §6.4 *Replies*.
3
+ *
4
+ * Two reply shapes, one per kind, and they do not mix:
5
+ *
6
+ * - **A reply to a comment is a flat `kind:1111`.** Uppercase `A`/`K`/`P` are
7
+ * the object; lowercase `e`/`k`/`p` name the thread's top-level comment,
8
+ * never another reply. A reader that meets a reply to a reply anyway SHOULD
9
+ * walk its parents to the top-level comment rather than drop it.
10
+ * - **A reply in a channel stays a `kind:9`**, threaded by Buzz's
11
+ * `thread_tags`: `['e', <root>, '', 'reply']` for a direct reply, and a
12
+ * `root`/`reply` pair for a nested one. A reader files a nested one under
13
+ * its `root`-marked `e`, which names the thread, rather than dropping it
14
+ * because its parent is not a root.
15
+ */
16
+ import type { SignedEvent } from '@estiva-app/protocol'
17
+ import { KIND_COMMENT } from './kinds.js'
18
+ import { byOrder } from './order.js'
19
+
20
+ type Tagged = Pick<SignedEvent, 'kind' | 'tags'>
21
+
22
+ /** The `e` tags that can thread: a NIP-10 `mention`-marked one quotes an event and answers nothing. */
23
+ const es = (event: Pick<SignedEvent, 'tags'>) =>
24
+ event.tags.filter((t) => t[0] === 'e' && typeof t[1] === 'string' && t[1] !== '' && t[3] !== 'mention')
25
+
26
+ /**
27
+ * The event this one answers, or null when it is a root.
28
+ *
29
+ * - `kind:1111`: the lowercase `e` that is not its `E` — the parent comment.
30
+ * A top-level comment on an event root carries `E` and `e` naming the same
31
+ * event, and is a root.
32
+ * - `kind:9` (and any other kind): the thread — the `root`-marked `e`, else
33
+ * the `reply`-marked one, else the first unmarked `e` when there is only one,
34
+ * else the first of several (NIP-10's positional form).
35
+ */
36
+ export function parentOf(event: Tagged): string | null {
37
+ const tags = es(event)
38
+ if (tags.length === 0) return null
39
+ if (event.kind === KIND_COMMENT) {
40
+ const root = event.tags.find((t) => t[0] === 'E')?.[1]
41
+ return tags.find((t) => t[1] !== root)?.[1] ?? null
42
+ }
43
+ const marked = (marker: string) => tags.find((t) => t[3] === marker)?.[1]
44
+ return marked('root') ?? marked('reply') ?? tags[0][1]
45
+ }
46
+
47
+ /** A conversation's events, threaded. */
48
+ export interface Threaded<E extends Tagged & Pick<SignedEvent, 'id' | 'created_at'>> {
49
+ /** The roots present in the read, oldest first. */
50
+ roots: E[]
51
+ /**
52
+ * Every reply per thread, keyed by the thread's root id, oldest first. A
53
+ * reply to a reply is filed under the thread's root, not its parent. A root
54
+ * with no replies is absent, not `[]`.
55
+ */
56
+ replies: Record<string, E[]>
57
+ /**
58
+ * Thread roots that replies point at but the read does not hold — deleted,
59
+ * or outside the read. Their replies are in `replies` under that id; what to
60
+ * draw in the root's place is the app's (Peek draws "This comment was
61
+ * deleted", PER-24).
62
+ */
63
+ missingRoots: string[]
64
+ }
65
+
66
+ /**
67
+ * Thread a conversation: every root, and every reply filed under its thread's
68
+ * root by walking parents (§6.4). Duplicate ids are read once; order is
69
+ * §6.3's.
70
+ */
71
+ export function groupThreads<E extends Tagged & Pick<SignedEvent, 'id' | 'created_at'>>(events: readonly E[]): Threaded<E> {
72
+ const byId = new Map<string, E>()
73
+ for (const event of events) if (!byId.has(event.id)) byId.set(event.id, event)
74
+
75
+ const rootOf = (event: E): string => {
76
+ const visited = new Set<string>([event.id])
77
+ let parent = parentOf(event)
78
+ while (parent !== null) {
79
+ const next = byId.get(parent)
80
+ if (!next || visited.has(parent)) return parent
81
+ visited.add(parent)
82
+ const up = parentOf(next)
83
+ if (up === null) return parent
84
+ parent = up
85
+ }
86
+ return event.id
87
+ }
88
+
89
+ const roots: E[] = []
90
+ const replies: Record<string, E[]> = {}
91
+ const missing = new Set<string>()
92
+ for (const event of byId.values()) {
93
+ const root = rootOf(event)
94
+ if (root === event.id) {
95
+ roots.push(event)
96
+ continue
97
+ }
98
+ ;(replies[root] ??= []).push(event)
99
+ if (!byId.has(root)) missing.add(root)
100
+ }
101
+ roots.sort(byOrder)
102
+ for (const list of Object.values(replies)) list.sort(byOrder)
103
+ return { roots, replies, missingRoots: [...missing] }
104
+ }