@estiva-app/conversation 0.25.0 → 0.27.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/src/membership.ts CHANGED
@@ -27,10 +27,10 @@
27
27
  * Muting is private and separate (§11.8 *Muting is private*): see
28
28
  * {@link parseMutedBlob}.
29
29
  */
30
- import type { SignedEvent, UnsignedEvent } from '@estiva-app/protocol'
30
+ import { fileIdOf, type SignedEvent, type UnsignedEvent } from '@estiva-app/protocol'
31
31
  import { FILE_ADDRESS as ADDRESS, FOLDER_ID, KIND_APP_DATA, KIND_CHANGE, KIND_COMMENT, KIND_MESSAGE } from './kinds.js'
32
32
  import { byOrder } from './order.js'
33
- import { anchorsOf, isCommentOn, peopleNamedInBody } from './strength.js'
33
+ import { anchorsOf, isAbout, isCommentOn, peopleNamedInBody } from './strength.js'
34
34
  import { groupThreads } from './threads.js'
35
35
 
36
36
  export { KIND_CHANGE }
@@ -92,7 +92,7 @@ export function streamOf<E extends Event>(file: string, events: readonly E[]): E
92
92
  out.push(root, ...(replies[root.id] ?? []))
93
93
  }
94
94
  for (const id of missing) {
95
- for (const reply of replies[id] ?? []) if (reply.kind === KIND_COMMENT && anchorsOf(reply).includes(file)) out.push(reply)
95
+ for (const reply of replies[id] ?? []) if (reply.kind === KIND_COMMENT && isAbout(reply, file)) out.push(reply)
96
96
  }
97
97
  return out.sort(byOrder)
98
98
  }
@@ -134,8 +134,16 @@ function stepsOf(file: string, events: readonly Event[]): Map<string, Step[]> {
134
134
  for (const person of peopleNamedInBody(message.content)) add(person, message, true)
135
135
  }
136
136
 
137
+ const id = file.split(':').slice(2).join(':')
137
138
  for (const change of events) {
138
- if (change.kind !== KIND_CHANGE || !change.tags.some((t) => t[0] === 'a' && t[1] === file)) continue
139
+ if (change.kind !== KIND_CHANGE || !isChangeTo(change, file, id)) continue
140
+ const sets = change.tags.filter((t) => t[0] === 'set' && typeof t[1] === 'string')
141
+ if (sets.length) {
142
+ // A several-field change never carries a `member:<P>` (§11.8), so one is not read here;
143
+ // the `p` it carries places people when any field it sets has a value.
144
+ if (sets.some((t) => !t[1].startsWith(MEMBER_FIELD_PREFIX) && t[2])) addNamed(change)
145
+ continue
146
+ }
139
147
  const field = tag(change, 'field')
140
148
  const value = tag(change, 'value')
141
149
  const member = memberOfField(field)
@@ -146,9 +154,25 @@ function stepsOf(file: string, events: readonly Event[]): Map<string, Step[]> {
146
154
  }
147
155
  // A change with an empty value takes someone off (an unassign) and places nobody, whatever `p` it carries.
148
156
  if (field?.startsWith(MEMBER_FIELD_PREFIX) || !value) continue
149
- for (const t of change.tags) if (t[0] === 'p' && typeof t[1] === 'string') add(t[1], change, true)
157
+ addNamed(change)
150
158
  }
151
159
  return steps
160
+
161
+ function addNamed(change: Event) {
162
+ for (const t of change.tags) if (t[0] === 'p' && typeof t[1] === 'string') add(t[1], change, true)
163
+ }
164
+ }
165
+
166
+ /**
167
+ * Whether a change is to the file: its first `a` names it, the one the relay
168
+ * checks the change against, and any `O` is the file's id. A change with no
169
+ * `a` is checked against nothing, so it is to no file; one whose `O` is not
170
+ * its `a`'s file is about neither (§6.2).
171
+ */
172
+ function isChangeTo(change: Pick<SignedEvent, 'tags'>, file: string, id: string): boolean {
173
+ const O = tag(change, 'O')
174
+ if (O !== undefined && O !== id) return false
175
+ return tag(change, 'a') === file
152
176
  }
153
177
 
154
178
  function fold(steps: readonly Step[] | undefined): Membership {
@@ -216,7 +240,7 @@ export function candidateFilesOf(event: Pick<SignedEvent, 'kind' | 'tags'>): str
216
240
  /**
217
241
  * A membership change (§11.8 *The membership change*): `true` adds a person,
218
242
  * by anyone; `false` is a leave and counts only when the person signs it
219
- * themselves. Tag order: `a`, `field`, `value`, `h`, `ts`, `p`.
243
+ * themselves. Tag order: `a`, `[O]`, `field`, `value`, `h`, `ts`, `p`.
220
244
  *
221
245
  * Sign one only when the person chose it — joining, leaving, or adding
222
246
  * somebody. Never to migrate a private follow (§11.8 *Following, retired*).
@@ -240,6 +264,8 @@ export function buildMembershipChange(
240
264
  kind: KIND_CHANGE,
241
265
  tags: [
242
266
  ['a', args.file],
267
+ // The file the change is about, by its id (§6.2, §11.8): the same file, so additive for every reader.
268
+ ...(fileIdOf(args.file) !== undefined ? [['O', fileIdOf(args.file)!]] : []),
243
269
  ['field', memberField(args.person)],
244
270
  ['value', args.member ? 'true' : 'false'],
245
271
  ['h', args.folder],
package/src/readState.ts CHANGED
@@ -24,6 +24,7 @@
24
24
  */
25
25
  import type { SignedEvent, UnsignedEvent } from '@estiva-app/protocol'
26
26
  import { FILE_ADDRESS as ADDRESS_RE, FOLDER_ID as UUID_RE, KIND_APP_DATA } from './kinds.js'
27
+ import { fileIdFormOf, fileIdOf, isFileId } from '@estiva-app/protocol'
27
28
  import type { QueryFn } from './decorations.js'
28
29
 
29
30
  /** NIP-RS's own `t` tag. */
@@ -105,6 +106,56 @@ export function fileContext(address: string | null | undefined): string | undefi
105
106
  return ADDRESS_RE.test(address) ? address : undefined
106
107
  }
107
108
 
109
+ /**
110
+ * A file's context by its id: `file:<d>`, for a lowercase UUID (§11.1, *added
111
+ * 2026-10-30*). Where a new read of a file is written once its comments name
112
+ * it by id; {@link streamMarkerOf} reads it beside the address key.
113
+ *
114
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-files-unread-state-is-keyed-file-and-its-id.md
115
+ */
116
+ export function fileIdContext(id: string | null | undefined): string | undefined {
117
+ return id && isFileId(id) ? `${FILE_ID_PREFIX}${id}` : undefined
118
+ }
119
+
120
+ const FILE_ID_PREFIX = 'file:'
121
+
122
+ /**
123
+ * The markers a read of a file writes, for `advanceContexts`: under
124
+ * `file:<d>` once the relay keeps the file's type in order (`inOrder`,
125
+ * `RelayFileReads.inOrder`), and under its address too, while an app that
126
+ * reads only the address key remains (§11.6, *added 2026-11-02*). Before the
127
+ * switch, under its address alone. Empty for anything that is not a file's
128
+ * address.
129
+ *
130
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-files-unread-state-is-keyed-file-and-its-id.md
131
+ */
132
+ export function fileReadMarkers(address: string, at: number, inOrder: readonly string[] = []): Record<string, number> {
133
+ const byAddress = fileContext(address)
134
+ if (byAddress === undefined) return {}
135
+ const byId = fileIdContext(fileIdFormOf(inOrder, address)?.id)
136
+ return byId === undefined ? { [byAddress]: at } : { [byId]: at, [byAddress]: at }
137
+ }
138
+
139
+ /**
140
+ * A stream's marker. For a file, the later of its address key and its
141
+ * `file:<d>` key (§11.1, §11.6, *added 2026-11-02*): either one is a marker,
142
+ * so a file whose comments moved to its id keeps what was read, whichever form
143
+ * the stream is passed in. A `file:<d>` stream reads every address key whose
144
+ * `d` is that id. Any other stream reads its own key.
145
+ */
146
+ export function streamMarkerOf(merged: Readonly<Record<string, number>>, stream: string): number | undefined {
147
+ const own = merged[stream]
148
+ if (ADDRESS_RE.test(stream)) {
149
+ const byId = fileIdContext(fileIdOf(stream))
150
+ return byId === undefined ? own : later(own, merged[byId])
151
+ }
152
+ if (!stream.startsWith(FILE_ID_PREFIX)) return own
153
+ const id = stream.slice(FILE_ID_PREFIX.length)
154
+ let out: number | undefined = own
155
+ for (const [key, at] of Object.entries(merged)) if (ADDRESS_RE.test(key) && fileIdOf(key) === id) out = later(out, at)
156
+ return out
157
+ }
158
+
108
159
  /** `thread:<root-event-id>`, NIP-RS's own scheme. */
109
160
  export function threadContext(rootEventId: string | null | undefined): string | undefined {
110
161
  if (!rootEventId) return undefined
@@ -136,6 +187,8 @@ export function isPublishableContextId(id: string): boolean {
136
187
  if (id.length === 0 || utf8(id) > MAX_CONTEXT_ID_BYTES) return false
137
188
  if (id.startsWith('thread:')) return EVENT_ID_RE.test(id.slice('thread:'.length))
138
189
  if (id.startsWith('msg:')) return EVENT_ID_RE.test(id.slice('msg:'.length))
190
+ // A key beginning `file:` whose remainder is not a lowercase UUID is not a file context (§11.1).
191
+ if (id.startsWith(FILE_ID_PREFIX)) return isFileId(id.slice(FILE_ID_PREFIX.length))
139
192
  return UUID_RE.test(id) || ADDRESS_RE.test(id)
140
193
  }
141
194
 
@@ -450,7 +503,7 @@ export function effectiveReadAt(
450
503
  from: number = THREAD_RULE_FROM,
451
504
  ): number | undefined {
452
505
  const own = merged[context]
453
- const parent = stream === undefined ? undefined : merged[stream]
506
+ const parent = stream === undefined ? undefined : streamMarkerOf(merged, stream)
454
507
  if (isThreadKey(context)) return threadReadAt({ thread: own, stream: parent, floor: merged[REPLY_FLOOR_CONTEXT] }, from)
455
508
  return later(own, parent)
456
509
  }
package/src/strength.ts CHANGED
@@ -27,7 +27,7 @@
27
27
  * reply `e` — a `kind:9` with any `e`, a `kind:1111` with a lowercase `e` that
28
28
  * differs from its `E` — is not a comment of its own, whatever `a` it carries.
29
29
  */
30
- import { decodeNaddr, decodeNpub, findNaddrs, findNostrUris, pointerToAddress, type NostrTag, type SignedEvent } from '@estiva-app/protocol'
30
+ import { decodeNaddr, decodeNpub, findNaddrs, findNostrUris, FILE_KINDS, fileIdFormOf, fileIdOf, pointerToAddress, type NostrTag, type SignedEvent } from '@estiva-app/protocol'
31
31
  import { KIND_COMMENT } from './kinds.js'
32
32
 
33
33
  type Tagged = Pick<SignedEvent, 'kind' | 'tags'>
@@ -77,11 +77,76 @@ export function isReply(event: Pick<SignedEvent, 'kind' | 'tags'>): boolean {
77
77
  * test for whether the event itself lists as a comment.
78
78
  */
79
79
  export function anchorsOf(event: Tagged): string[] {
80
- if (event.kind !== KIND_COMMENT) return []
80
+ if (event.kind !== KIND_COMMENT || crossed(event)) return []
81
81
  const roots = values(event, 'A')
82
82
  return [...new Set(roots.length > 0 ? roots : values(event, 'a'))]
83
83
  }
84
84
 
85
+ /**
86
+ * The ids of the files the event's thread is about by its `O` tags (§6.4, "A
87
+ * comment in both forms"), beside {@link anchorsOf}'s addresses. Empty for a
88
+ * comment whose `A` and `O` name different files: that one is about neither.
89
+ */
90
+ export function anchorIdsOf(event: Tagged): string[] {
91
+ if (event.kind !== KIND_COMMENT || crossed(event)) return []
92
+ return [...new Set(values(event, 'O'))]
93
+ }
94
+
95
+ /**
96
+ * A comment §6.4 ignores, as a change is (§6.2): two `O`s or two `A`s, or a
97
+ * root and an `O` that name different files, or it would show under one file
98
+ * for a reader asking by address and under another for one asking `#O`. The
99
+ * root is its `A`, or its `a` when it carries no `A`, as {@link anchorsOf}
100
+ * reads it, and names the `O`'s file only as a file kind's address with that
101
+ * id. That the author is the file's is {@link isAbout}'s to check: the
102
+ * comment is about its root.
103
+ */
104
+ function crossed(event: Pick<SignedEvent, 'tags'>): boolean {
105
+ const ids = new Set(values(event, 'O'))
106
+ const roots = new Set(values(event, 'A'))
107
+ if (ids.size > 1 || roots.size > 1) return true
108
+ if (ids.size === 0) return false
109
+ const [id] = ids
110
+ return [...(roots.size > 0 ? roots : values(event, 'a'))].some(
111
+ (address) => !FILE_KINDS.includes(Number(address.split(':')[0])) || fileIdOf(address) !== id,
112
+ )
113
+ }
114
+
115
+ /** Whether the event is a comment whose root and `O` name different files: one ignored under every file (§6.4). */
116
+ export function isCrossedComment(event: Tagged): boolean {
117
+ return event.kind === KIND_COMMENT && crossed(event)
118
+ }
119
+
120
+ /**
121
+ * {@link isCrossedComment}, or a comment whose `O` has the id of the file at
122
+ * `address` under a root that is not that address (another author's): its
123
+ * root and `O` disagree for this file, so under it it is nothing, not even a
124
+ * mention (§6.4).
125
+ */
126
+ export function isCrossedCommentOn(event: Tagged, address: string): boolean {
127
+ if (event.kind !== KIND_COMMENT) return false
128
+ if (crossed(event)) return true
129
+ const roots = anchorsOf(event)
130
+ return roots.length > 0 && !roots.includes(address) && values(event, 'O').some((id) => namesById(id, address))
131
+ }
132
+
133
+ /**
134
+ * Whether a `kind:1111`'s thread is about the file at `address`: by its
135
+ * {@link anchorsOf} root when it has one, so an `O` with the file's id under
136
+ * an address of another author is not about it; by its `O` only when it
137
+ * carries neither `A` nor `a` (§6.4). A root or a reply alike;
138
+ * {@link isCommentOn} adds the root test.
139
+ */
140
+ export function isAbout(event: Tagged, address: string): boolean {
141
+ const roots = anchorsOf(event)
142
+ if (roots.length > 0) return roots.includes(address)
143
+ // No root: neither `A` nor `a`, or an ignored comment, whose `O`s are none.
144
+ return anchorIdsOf(event).some((id) => namesById(id, address))
145
+ }
146
+
147
+ /** Whether a tag naming a file by its id (`O`, `o`) names the file at `address`. */
148
+ const namesById = (id: string, address: string) => fileIdOf(address) === id
149
+
85
150
  /**
86
151
  * Is the event a **comment** on the address: a root whose thread is about it
87
152
  * (C10, C11).
@@ -98,14 +163,21 @@ export function anchorsOf(event: Tagged): string[] {
98
163
  */
99
164
  export function isCommentOn(event: Readable, address: string, declaredKinds: readonly number[] = [KIND_COMMENT]): boolean {
100
165
  if (isReply(event)) return false
101
- if (event.kind === KIND_COMMENT) return anchorsOf(event).includes(address)
166
+ if (event.kind === KIND_COMMENT) return isAbout(event, address)
102
167
  if (!declaredKinds.includes(event.kind)) return false
103
168
  return event.tags.some((t) => t[0] === 'a' && t[1] === address) && !namedInBody(event.content).has(address)
104
169
  }
105
170
 
106
- /** Does the event name the address at all — any `a` or `A`, or a `nostr:naddr…` in its body. */
171
+ /**
172
+ * Does the event name the address at all — any `a` or `A`, an `o` or `O` with
173
+ * the file's id (§6.4), or a `nostr:naddr…` in its body. A comment whose `A`
174
+ * and `O` disagree names nothing: it is ignored under every file (§6.4), and
175
+ * one whose `O` has this file's id under another address is about that one.
176
+ */
107
177
  export function referencesAddress(event: Readable, address: string): boolean {
178
+ if (isCrossedCommentOn(event, address)) return false
108
179
  if (event.tags.some((t) => (t[0] === 'a' || t[0] === 'A') && t[1] === address)) return true
180
+ if (event.tags.some((t) => (t[0] === 'o' || t[0] === 'O') && typeof t[1] === 'string' && namesById(t[1], address))) return true
109
181
  return namedInBody(event.content).has(address)
110
182
  }
111
183
 
@@ -147,11 +219,17 @@ export function threadStrength(root: Readable | undefined, replies: readonly Rea
147
219
  * §6.4: a writer MUST NOT put an address in a `kind:1111`'s `a` that the body
148
220
  * does not name, unless it is the `A` — which is what keeps the mention row
149
221
  * readable without decoding the body.
222
+ *
223
+ * A file whose type the relay keeps in order (`inOrder`) earns an `o` with
224
+ * its id after its `a` (§6.4).
150
225
  */
151
- export function referenceTagsFor(body: string, own = ''): NostrTag[] {
226
+ export function referenceTagsFor(body: string, own = '', inOrder: readonly string[] = []): NostrTag[] {
152
227
  const addresses = namedInBody(body)
153
228
  addresses.delete(own)
154
- return [...addresses].map((a) => ['a', a])
229
+ return [...addresses].flatMap((a) => {
230
+ const byId = fileIdFormOf(inOrder, a)
231
+ return byId ? [['a', a], ['o', byId.id]] : [['a', a]]
232
+ })
155
233
  }
156
234
 
157
235
  /** The most `p` tags a message carries — Buzz's cap, and `buildMessage`'s. */
package/src/unread.ts CHANGED
@@ -19,7 +19,7 @@
19
19
  * the caller's to decide by not asking.
20
20
  */
21
21
  import type { SignedEvent } from '@estiva-app/protocol'
22
- import { REPLY_FLOOR_CONTEXT, belowReplyFloor, effectiveReadAt, threadContext } from './readState.js'
22
+ import { REPLY_FLOOR_CONTEXT, belowReplyFloor, effectiveReadAt, streamMarkerOf, threadContext } from './readState.js'
23
23
  import { peopleNamedInBody } from './strength.js'
24
24
  import { groupThreads } from './threads.js'
25
25
 
@@ -78,7 +78,7 @@ export function isUnread(message: Message, root: string | undefined, merged: Rea
78
78
  if (!mentioned && (!judge.member || judge.muted)) return false
79
79
  if (judge.since !== undefined && message.created_at < judge.since) return false
80
80
  const thread = root === undefined ? undefined : threadContext(root)
81
- const marker = thread === undefined ? merged[judge.stream] : effectiveReadAt(merged, thread, judge.stream)
81
+ const marker = thread === undefined ? streamMarkerOf(merged, judge.stream) : effectiveReadAt(merged, thread, judge.stream)
82
82
  if (marker !== undefined) return message.created_at > marker
83
83
  if (thread !== undefined && belowReplyFloor(message.created_at, merged[REPLY_FLOOR_CONTEXT])) return false
84
84
  if (judge.since !== undefined) return true