@estiva-app/interop 0.68.0 → 0.69.1

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/interop",
3
- "version": "0.68.0",
3
+ "version": "0.69.1",
4
4
  "description": "Render and act on another app's objects from its published NIP-89 manifest. The owner defines the projection; the consumer decides how it looks.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -47,12 +47,12 @@
47
47
  "prepublishOnly": "npm run build"
48
48
  },
49
49
  "peerDependencies": {
50
- "@estiva-app/conversation": ">=0.6.1",
51
- "@estiva-app/protocol": ">=0.24.0"
50
+ "@estiva-app/conversation": ">=0.20.0",
51
+ "@estiva-app/protocol": ">=0.44.0"
52
52
  },
53
53
  "devDependencies": {
54
- "@estiva-app/conversation": ">=0.6.1",
55
- "@estiva-app/protocol": ">=0.24.0",
54
+ "@estiva-app/conversation": ">=0.20.0",
55
+ "@estiva-app/protocol": ">=0.44.0",
56
56
  "typescript": "~5.9.3"
57
57
  }
58
58
  }
package/src/index.ts CHANGED
@@ -147,6 +147,32 @@ export {
147
147
  type MoveRefusal,
148
148
  } from './folders.js'
149
149
 
150
+ /**
151
+ * What an app link names, and where a file is mentioned — once for every app
152
+ * (SPEC §7.7, §13.1, §6.8; PEEKM-7). Each app passes its relay read; none
153
+ * keeps a resolver of its own.
154
+ */
155
+ export {
156
+ linkReader,
157
+ linkTagsOf,
158
+ linksIn,
159
+ writtenOpenerOf,
160
+ within,
161
+ MAX_LINKS_ASKED,
162
+ type LinkAnswer,
163
+ type LinkReader,
164
+ type LinkReaderOptions,
165
+ type OwnPlace,
166
+ } from './links.js'
167
+ export {
168
+ mentionedInFilter,
169
+ mentionedInOf,
170
+ readMentionedIn,
171
+ MENTIONED_IN_LIMIT,
172
+ MAX_MENTIONED_IN_LINKS_ASKED,
173
+ type MentionedIn,
174
+ } from './mentions.js'
175
+
150
176
  /**
151
177
  * RFC 0.5 §7's URL grammar — how an object is named in an address bar, and how
152
178
  * a pasted link is matched back to one.
package/src/links.ts ADDED
@@ -0,0 +1,312 @@
1
+ /**
2
+ * What an app link names, once for every app — SPEC §7.7, §13.1, §13.6.2
3
+ * (PEEKM-7). The chip a pasted link becomes, the card under a comment, the
4
+ * block a link to one block shows, the `a` and `q` tags a send or an edit
5
+ * carries, and where a card written as a URL opens: Peek, Ship, Leaf and the
6
+ * agent each kept a copy of this, and they drifted (Leaf retried, Ship tagged
7
+ * a URL in code, only Leaf's opener was https only).
8
+ *
9
+ * A URL names an object when a published manifest's `urls` pattern claims its
10
+ * host and `<type>`, and then **one author** holds that `d`: the `#d` query
11
+ * asks for two, and a `d` two authors hold names nothing, so somebody
12
+ * publishing the same `(kind, d)` cannot put their object's card or its
13
+ * mention under a link to another's. Only an addressable kind is asked: a
14
+ * manifest anyone can publish could otherwise point a path at a kind where a
15
+ * `d` is no identity. A link to one block (`#block-<id>`) names its file, and
16
+ * the block is its part (§13.6.1). A URL that names an event names its id.
17
+ *
18
+ * Asked once per link for the reader's life: a link names the same object for
19
+ * as long as its owner's manifest does. A read that failed is forgotten, so the
20
+ * next ask tries again, and is said as a change after 5, 10 and 20 seconds so
21
+ * whoever still draws from it asks.
22
+ *
23
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-files-path-is-the-same-on-every-apps-host.md
24
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/an-edit-says-what-the-message-links-now.md
25
+ */
26
+ import { MAX_PARTS } from '@estiva-app/conversation'
27
+ import { partTag, valuesIn, type LinkResolver, type PartPointer, type RenderBlock } from '@estiva-app/protocol'
28
+ import { matchObjectUrl, urlPatternsOf, type UrlPattern } from './objectUrl.js'
29
+ import type { QueryFn } from './projection.js'
30
+
31
+ /** What one link names: an address or a message's event id, and the block when it links to one. */
32
+ export interface LinkAnswer {
33
+ value: string | null
34
+ block?: PartPointer
35
+ }
36
+
37
+ /** The comment a body is written in: its file and the message it replies to, which its tags never repeat as a mention. */
38
+ export interface OwnPlace {
39
+ /** The file the comment is on, `kind:pubkey:d`: its `A`, never also an `a` for a link to it. */
40
+ file?: string
41
+ /** The event id it replies to: its `e`, never also a `q`. */
42
+ parent?: string
43
+ }
44
+
45
+ export interface LinkReaderOptions {
46
+ /** A read as the viewer. Throws when the relay could not be asked. */
47
+ query: QueryFn
48
+ /**
49
+ * The published manifests, `kind:31990` (§7.2). Omitted: one read of every
50
+ * manifest through `query`, kept for the reader's life and forgotten when it
51
+ * fails. An app that already holds them passes its own.
52
+ */
53
+ manifests?: () => Promise<readonly { tags: string[][] }[]>
54
+ /** How many times a failed read is said as a change, after 5, 10, 20… seconds. Default 3; 0 says none. */
55
+ retries?: number
56
+ }
57
+
58
+ export interface LinkReader {
59
+ /** What one link names; rejects when the relay could not be asked (and the next ask tries again). */
60
+ answerOf(url: string): Promise<LinkAnswer>
61
+ /**
62
+ * Ask what each of these links names; settles when every answer is in, and
63
+ * rejects when a read failed (it left no answer), so a `LinkChips` forgets
64
+ * those links and asks again.
65
+ */
66
+ ask(urls: readonly string[]): Promise<void>
67
+ /** What a link names, from what has come back: undefined until it has, and for nothing. A `LinkResolver`. */
68
+ known: LinkResolver
69
+ /** The file and block a link to one block names, from what has come back. */
70
+ knownBlock(url: string): PartPointer | undefined
71
+ /** Whether a link's answer has come back, naming something or nothing. */
72
+ answered(url: string): boolean
73
+ /** Called each time an answer comes back, or a failed one may be asked again. Returns the unsubscribe. */
74
+ changed(listener: () => void): () => void
75
+ /** How many times {@link changed} has fired: a snapshot for `useSyncExternalStore`. */
76
+ version(): number
77
+ /**
78
+ * The `a`, `q` and `part` tags a body earns ({@link linkTagsOf}), asking
79
+ * first what its links name and waiting at most `waitMs` (default 5 s): a
80
+ * link not answered by then earns nothing, and the body keeps it.
81
+ */
82
+ tagsFor(blocks: readonly RenderBlock[], own: OwnPlace, options?: { waitMs?: number; edit?: boolean }): Promise<string[][]>
83
+ /** {@link writtenOpenerOf} against the hosts the manifests read so far declare. */
84
+ opener(url: string | undefined, opens: string | undefined, origin: string): string | undefined
85
+ /** Every host an app declares its paths on, as the manifests read so far said. */
86
+ declaredOrigins(): ReadonlySet<string>
87
+ }
88
+
89
+ // The runtime's, in every app and in node; this package compiles without the DOM or node types.
90
+ declare const URL: { new (raw: string, base?: string): { origin: string } }
91
+ declare const setTimeout: (run: () => void, ms: number) => unknown
92
+ declare const clearTimeout: (timer: unknown) => void
93
+
94
+ /** Wait for `work`, but no longer than `ms`; never rejects. */
95
+ export async function within(work: Promise<unknown>, ms: number): Promise<void> {
96
+ let timer: unknown
97
+ await Promise.race([
98
+ work.then(
99
+ () => {},
100
+ () => {},
101
+ ),
102
+ new Promise<void>((resolve) => {
103
+ timer = setTimeout(resolve, ms)
104
+ }),
105
+ ])
106
+ clearTimeout(timer)
107
+ }
108
+
109
+ /** How many links one body asks about, the first ones — as `LinkChips`' `limit`: each answer can cost a relay query. */
110
+ export const MAX_LINKS_ASKED = 24
111
+
112
+ const EVENT_ID = /^[0-9a-f]{64}$/i
113
+ const RETRY_MS = 5000
114
+
115
+ /** NIP-89's handler information, where an app publishes its manifest and `urls` (§7.2). */
116
+ const KIND_APP_HANDLER = 31990
117
+
118
+ /** One link reader for an app: its relay reads, and the manifests it holds. */
119
+ export function linkReader(options: LinkReaderOptions): LinkReader {
120
+ const { query, retries = 3 } = options
121
+ const origins = new Set<string>()
122
+ let shapes: Promise<UrlPattern[]> | null = null
123
+ const shapesOf = (): Promise<UrlPattern[]> => {
124
+ if (shapes) return shapes
125
+ const read = (options.manifests ?? (() => query([{ kinds: [KIND_APP_HANDLER], limit: 500 }])))().then((manifests) => {
126
+ const found = manifests.flatMap((manifest) => urlPatternsOf(manifest))
127
+ for (const shape of found) {
128
+ try {
129
+ origins.add(new URL(shape.pattern).origin)
130
+ } catch {
131
+ // A shape that is not a URL declares no host.
132
+ }
133
+ }
134
+ return found
135
+ })
136
+ shapes = read
137
+ // A failed read must not poison the reader, nor an empty one (a relay still
138
+ // starting, a read before sign-in): the next link asks again.
139
+ read.then(
140
+ (found) => {
141
+ if (found.length === 0 && shapes === read) shapes = null
142
+ },
143
+ () => {
144
+ if (shapes === read) shapes = null
145
+ },
146
+ )
147
+ return read
148
+ }
149
+
150
+ const answer = async (url: string): Promise<LinkAnswer> => {
151
+ const shapes = await shapesOf()
152
+ // No manifest read yet is no answer: kept as one, the link would name nothing for the reader's life.
153
+ if (shapes.length === 0) throw new Error('No app manifest has been read yet.')
154
+ const hit = matchObjectUrl(url, shapes)
155
+ if (!hit) return { value: null }
156
+ if (hit.by === 'id') return { value: EVENT_ID.test(hit.identifier) ? hit.identifier.toLowerCase() : null }
157
+ // A path on another app's host can read as several kinds (§7.7, LTX-6): ask under each addressable one.
158
+ const kinds = (hit.kinds ?? (hit.kind === undefined ? undefined : [hit.kind]))?.filter((kind) => kind >= 30000 && kind < 40000)
159
+ if (kinds?.length === 0) return { value: null }
160
+ // A shape that names no kind asks every one; only an addressable answer counts.
161
+ const found = (await query([{ '#d': [hit.identifier], limit: 2, ...(kinds ? { kinds } : {}) }])).filter((event) => event.kind >= 30000 && event.kind < 40000)
162
+ const authors = new Set(found.map((event) => `${event.kind}:${event.pubkey.toLowerCase()}`))
163
+ if (authors.size !== 1) return { value: null }
164
+ const address = `${[...authors][0]}:${hit.identifier}`
165
+ return hit.block === undefined ? { value: address } : { value: address, block: { address, block: hit.block } }
166
+ }
167
+
168
+ const asked = new Map<string, Promise<LinkAnswer>>()
169
+ const known = new Map<string, LinkAnswer>()
170
+ const failures = new Map<string, number>()
171
+ const listeners = new Set<() => void>()
172
+ let answered = 0
173
+ const changed = () => {
174
+ answered += 1
175
+ for (const listener of listeners) listener()
176
+ }
177
+
178
+ const answerOf = (url: string): Promise<LinkAnswer> => {
179
+ let pending = asked.get(url)
180
+ if (!pending) {
181
+ pending = answer(url).then(
182
+ (found) => {
183
+ known.set(url, found)
184
+ changed()
185
+ return found
186
+ },
187
+ (error: unknown) => {
188
+ asked.delete(url)
189
+ const failed = failures.get(url) ?? 0
190
+ failures.set(url, failed + 1)
191
+ if (failed < retries) setTimeout(changed, RETRY_MS * 2 ** failed)
192
+ throw error
193
+ },
194
+ )
195
+ asked.set(url, pending)
196
+ }
197
+ return pending
198
+ }
199
+
200
+ const knownValue: LinkResolver = (url) => known.get(url)?.value ?? undefined
201
+ const knownBlock = (url: string) => known.get(url)?.block
202
+
203
+ return {
204
+ answerOf,
205
+ async ask(urls) {
206
+ const waiting = [...new Set(urls)].filter((url) => !known.has(url))
207
+ await Promise.allSettled(waiting.map(answerOf))
208
+ if (waiting.some((url) => !known.has(url))) throw new Error('A link could not be asked about; asked again later.')
209
+ },
210
+ known: knownValue,
211
+ knownBlock,
212
+ answered: (url) => known.has(url),
213
+ changed(listener) {
214
+ listeners.add(listener)
215
+ return () => {
216
+ listeners.delete(listener)
217
+ }
218
+ },
219
+ version: () => answered,
220
+ async tagsFor(blocks, own, { waitMs = 5000, edit = false } = {}) {
221
+ const urls = linksIn(blocks).slice(0, MAX_LINKS_ASKED)
222
+ const waiting = urls.filter((url) => !known.has(url))
223
+ if (waiting.length > 0) await within(Promise.allSettled(waiting.map(answerOf)), waitMs)
224
+ const first = new Set(urls)
225
+ const resolve: LinkResolver = (url) => (first.has(url) ? knownValue(url) : undefined)
226
+ return linkTagsOf(blocks, own, resolve, edit ? undefined : (url) => (first.has(url) ? knownBlock(url) : undefined))
227
+ },
228
+ opener: (url, opens, origin) => writtenOpenerOf(url, opens, origin, origins),
229
+ declaredOrigins: () => origins,
230
+ }
231
+ }
232
+
233
+ /**
234
+ * Every link a body names something by, in the order it names them: the URLs
235
+ * {@link valuesIn} asks a `LinkResolver` about — bare, or a link on words'
236
+ * target, and none in code. What a sender asks about before it tags.
237
+ */
238
+ export function linksIn(blocks: readonly RenderBlock[]): string[] {
239
+ const urls: string[] = []
240
+ valuesIn(blocks, (url) => {
241
+ urls.push(url)
242
+ return undefined
243
+ })
244
+ return [...new Set(urls)]
245
+ }
246
+
247
+ /**
248
+ * The tags a message's body earns for what it names (§13.1, §13.6.1): an `a`
249
+ * per address and a `q` per message, by a `nostr:` reference or an app link
250
+ * `resolve` answers, in the order the body first names them; then one `part`
251
+ * per file a link to one of its blocks names, the first link's, when
252
+ * `blockOf` is given. The comment's own file earns neither an `a` nor a part
253
+ * (it is the `A`), and the message it replies to no `q` (it is the `e`).
254
+ *
255
+ * A send and an edit carry the same `a` and `q` set: an edit says what the
256
+ * message links now. An edit carries no `part` (pass no `blockOf`), and a
257
+ * person is never here: `p` and `urgent` stay as the send wrote them.
258
+ *
259
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/an-edit-says-what-the-message-links-now.md
260
+ */
261
+ export function linkTagsOf(
262
+ blocks: readonly RenderBlock[],
263
+ own: OwnPlace,
264
+ resolve: LinkResolver,
265
+ blockOf?: (url: string) => PartPointer | undefined,
266
+ ): string[][] {
267
+ const file = own.file && sameValue(own.file)
268
+ const parent = own.parent?.toLowerCase()
269
+ const tags: string[][] = []
270
+ for (const value of valuesIn(blocks, resolve)) {
271
+ if (EVENT_ID.test(value)) {
272
+ if (value !== parent) tags.push(['q', value])
273
+ } else if (value !== file) tags.push(['a', value])
274
+ }
275
+ if (blockOf) {
276
+ const parts = new Map<string, string>()
277
+ for (const url of linksIn(blocks)) {
278
+ const part = blockOf(url)
279
+ if (part && sameValue(part.address) !== file && !parts.has(part.address)) parts.set(part.address, part.block)
280
+ }
281
+ // As many as a box shows under it (conversation's `boxLinksOf`): a part the box did not draw is not sent.
282
+ for (const [address, block] of [...parts].slice(0, MAX_PARTS)) tags.push(partTag(address, block))
283
+ }
284
+ return tags
285
+ }
286
+
287
+ /** An address as `valuesIn` spells it: the kind and pubkey as hex, the `d` as written. */
288
+ function sameValue(address: string): string {
289
+ const [kind, pubkey = '', ...d] = address.split(':')
290
+ return `${kind}:${pubkey.toLowerCase()}:${d.join(':')}`
291
+ }
292
+
293
+ /**
294
+ * Where a card or chip written as a URL opens: the address as written, in the
295
+ * app it names (§7.7, LTX-6), so `leaf.estiva.app/issue/…` opens Leaf, not
296
+ * Ship. Undefined for anything but https, and for a host that is neither this
297
+ * app's (`origin`), the one its file opens on (`opens`), nor one an app
298
+ * declares: a card that draws one file never opens a site no app serves from
299
+ * (WBM-11 security review). The same rule in every app.
300
+ *
301
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-files-path-is-the-same-on-every-apps-host.md
302
+ */
303
+ export function writtenOpenerOf(url: string | undefined, opens: string | undefined, origin: string, declared: ReadonlySet<string>): string | undefined {
304
+ if (!url || !/^https:\/\//i.test(url)) return undefined
305
+ try {
306
+ const at = new URL(url).origin
307
+ const opensAt = opens ? new URL(opens, origin).origin : undefined
308
+ return at === origin || at === opensAt || declared.has(at) ? url : undefined
309
+ } catch {
310
+ return undefined
311
+ }
312
+ }
@@ -0,0 +1,140 @@
1
+ /**
2
+ * Where a file is mentioned — its "Mentioned in", once for every app (SPEC
3
+ * §6.4, §6.8, PEEKM-7). Peek's file panel and Ship's Activity each read it
4
+ * their own way: Peek dropped a row an edit took a `nostr:` reference out of,
5
+ * Ship kept every first version, and neither saw a link an edit added.
6
+ *
7
+ * A file lists a message while the message's **latest words** link it. The
8
+ * candidates are every message, comment and edit pointing at the file by `a`
9
+ * (an edit carries the `a` its new words earn); an edit stands for the message
10
+ * it edits; and each is confirmed against the folded body, by a `nostr:`
11
+ * reference or an app link that names the file. A message the reader cannot
12
+ * read lists nothing, whatever its edits point at. The file's own conversation
13
+ * is not a mention of it.
14
+ *
15
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/an-edit-says-what-the-message-links-now.md
16
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/activity-lists-only-mentions-from-elsewhere.md
17
+ */
18
+ import { anchorsOf, editsByTarget, editTargetOf, isCommentOn, KIND_COMMENT, KIND_EDIT, KIND_MESSAGE } from '@estiva-app/conversation'
19
+ import { toRenderTree, valuesIn, type LinkResolver, type SignedEvent } from '@estiva-app/protocol'
20
+ import { linksIn, within, MAX_LINKS_ASKED, type LinkReader } from './links.js'
21
+ import type { QueryFn } from './projection.js'
22
+
23
+ /** One message that mentions the file, as its latest words say. */
24
+ export interface MentionedIn {
25
+ /** The message as sent: a `kind:1111` comment or a `kind:9` message. Where it was said, its thread, its author. */
26
+ event: SignedEvent
27
+ /** Its latest words: the latest edit's, or its own. */
28
+ body: string
29
+ /** The latest edit, when there is one: its files and cards replace the message's (§6.8). */
30
+ edit?: SignedEvent
31
+ }
32
+
33
+ /** Enough for a list that is scanned, not read; the oldest pointers are what a cap drops. */
34
+ export const MENTIONED_IN_LIMIT = 200
35
+
36
+ /**
37
+ * How many links one Mentioned-in read asks about in all, newest messages
38
+ * first. Each asked link is a relay query, and {@link MENTIONED_IN_LIMIT}
39
+ * candidates at {@link MAX_LINKS_ASKED} each would be 4,800 of them for one
40
+ * panel (PEEKM-7's review). A link left over stays unanswered, so a message
41
+ * pointing at the file keeps its row; a later read asks the next ones.
42
+ */
43
+ export const MAX_MENTIONED_IN_LINKS_ASKED = 64
44
+
45
+ /**
46
+ * The links of a message's words that can name the file: the first
47
+ * {@link MAX_LINKS_ASKED}, the ones a sender asks about before it tags. A link
48
+ * past them earned no `a`, so it is never asked about and keeps no row: a body
49
+ * of hundreds of links costs a reader no more than a sender.
50
+ */
51
+ const linksNaming = (tree: ReturnType<typeof toRenderTree>) => linksIn(tree).slice(0, MAX_LINKS_ASKED)
52
+
53
+ /** The one filter for the candidates: every message, comment and edit pointing at the file. */
54
+ export function mentionedInFilter(address: string, limit = MENTIONED_IN_LIMIT): Record<string, unknown> {
55
+ return { kinds: [KIND_COMMENT, KIND_MESSAGE, KIND_EDIT], '#a': [address], limit }
56
+ }
57
+
58
+ const isMessage = (event: SignedEvent) => event.kind === KIND_COMMENT || event.kind === KIND_MESSAGE
59
+
60
+ /**
61
+ * The messages among `events` that list under the file, newest first.
62
+ *
63
+ * `events` holds the candidates ({@link mentionedInFilter}), the messages their
64
+ * edits edit, and every edit of each message; `resolveLink` what the app links
65
+ * in their words name. `commentKinds` is the file's owner's comment kinds
66
+ * (`isCommentOn`): a message on the file itself is not a mention of it.
67
+ * `unanswered` says which links could not be asked about: a message whose
68
+ * latest version points at the file and holds one keeps its row until the
69
+ * link can be read, rather than lose it to a failed read.
70
+ */
71
+ export function mentionedInOf(
72
+ events: readonly SignedEvent[],
73
+ address: string,
74
+ resolveLink?: LinkResolver,
75
+ commentKinds?: readonly number[],
76
+ unanswered: (url: string) => boolean = () => false,
77
+ ): MentionedIn[] {
78
+ const messages = new Map<string, SignedEvent>()
79
+ for (const event of events) if (isMessage(event)) messages.set(event.id.toLowerCase(), event)
80
+ const edits = editsByTarget(events)
81
+ const pointed = new Set<string>()
82
+ for (const event of events) {
83
+ if (!event.tags.some((t) => t[0] === 'a' && t[1] === address)) continue
84
+ const id = event.kind === KIND_EDIT ? editTargetOf(event) : isMessage(event) ? event.id.toLowerCase() : undefined
85
+ if (id) pointed.add(id)
86
+ }
87
+ const file = valueOf(address)
88
+ const out: MentionedIn[] = []
89
+ for (const id of pointed) {
90
+ const event = messages.get(id)
91
+ if (!event) continue
92
+ if (anchorsOf(event).includes(address) || isCommentOn(event, address, commentKinds)) continue
93
+ // An edit by anyone but the author is not the message's (the relay refuses one; a reader does not trust that).
94
+ const edit = edits.get(id)?.filter((e) => e.pubkey === event.pubkey).at(-1)
95
+ const body = edit?.content ?? event.content
96
+ const tree = toRenderTree(body, 'marker')
97
+ const pointsNow = (edit ?? event).tags.some((t) => t[0] === 'a' && t[1] === address)
98
+ const first = linksNaming(tree)
99
+ const named = new Set(first)
100
+ const resolve: LinkResolver | undefined = resolveLink && ((url) => (named.has(url) ? resolveLink(url) : undefined))
101
+ if (!valuesIn(tree, resolve).includes(file) && !(pointsNow && first.some(unanswered))) continue
102
+ out.push(edit ? { event, body, edit } : { event, body })
103
+ }
104
+ return out.sort((a, b) => b.event.created_at - a.event.created_at)
105
+ }
106
+
107
+ /**
108
+ * {@link mentionedInOf} as the viewer: the candidates, then the messages their
109
+ * edits edit and every edit of each message, then what the links in their
110
+ * latest words name, asked through `links` and waited for at most `waitMs`.
111
+ * Throws when a read is refused, so an unreadable relay and a file nobody
112
+ * mentions are not the same empty list.
113
+ */
114
+ export async function readMentionedIn(
115
+ query: QueryFn,
116
+ address: string,
117
+ options: { links?: LinkReader; limit?: number; waitMs?: number; commentKinds?: readonly number[] } = {},
118
+ ): Promise<MentionedIn[]> {
119
+ const candidates = await query([mentionedInFilter(address, options.limit)])
120
+ const held = new Set(candidates.filter(isMessage).map((e) => e.id.toLowerCase()))
121
+ const missing = [...new Set(candidates.filter((e) => e.kind === KIND_EDIT).map(editTargetOf))].filter((id): id is string => !!id && !held.has(id))
122
+ const targets = missing.length ? await query([{ ids: missing, kinds: [KIND_COMMENT, KIND_MESSAGE] }]) : []
123
+ const ids = [...held, ...targets.map((e) => e.id.toLowerCase())]
124
+ const edits = ids.length ? await query([{ kinds: [KIND_EDIT], '#e': ids, limit: 1000 }]) : []
125
+ const events = [...candidates, ...targets, ...edits]
126
+ const links = options.links
127
+ if (!links) return mentionedInOf(events, address, undefined, options.commentKinds, () => true)
128
+ // The links that can name the file in each candidate's latest words: read as if each named it, so each candidate holding one is kept to ask.
129
+ // At most MAX_MENTIONED_IN_LINKS_ASKED, newest messages first; one left over stays unanswered, so a message pointing at the file keeps its row.
130
+ const urls = [...new Set(mentionedInOf(events, address, () => address, options.commentKinds).flatMap((m) => linksNaming(toRenderTree(m.body, 'marker'))))]
131
+ const waiting = urls.filter((url) => !links.answered(url)).slice(0, MAX_MENTIONED_IN_LINKS_ASKED)
132
+ if (waiting.length) await within(links.ask(waiting), options.waitMs ?? 5000)
133
+ return mentionedInOf(events, address, links.known, options.commentKinds, (url) => !links.answered(url))
134
+ }
135
+
136
+ /** The address as `valuesIn` spells it. */
137
+ function valueOf(address: string): string {
138
+ const [kind, pubkey = '', ...d] = address.split(':')
139
+ return `${kind}:${pubkey.toLowerCase()}:${d.join(':')}`
140
+ }
package/src/projection.ts CHANGED
@@ -227,6 +227,9 @@ export const KIND_MESSAGE = 9
227
227
  */
228
228
  const KIND_DELETION = 5
229
229
 
230
+ /** The tags a comment's body earns for what it names: `ActionEventArgs.linkTags`. */
231
+ const LINK_TAG_NAMES = new Set(['a', 'q', 'part'])
232
+
230
233
  /**
231
234
  * Every kind an app's comments might be under — what it publishes **now**, plus
232
235
  * any it has published before.
@@ -5810,6 +5813,14 @@ export interface ActionEventArgs {
5810
5813
  * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-reply-on-a-page-keeps-its-threads-place.md
5811
5814
  */
5812
5815
  replyTo?: { id: string; kind: number; author: string; place?: readonly string[][] }
5816
+ /**
5817
+ * The `a`, `q` and `part` tags a comment's body earns for what it names, by a
5818
+ * `nostr:` reference or an app link — {@link LinkReader.tagsFor}, asked by
5819
+ * the caller, which holds the relay (SPEC §13.1). Only for `comment`; any
5820
+ * other tag here is left out, and so is one naming the comment's own file or
5821
+ * the comment it answers.
5822
+ */
5823
+ linkTags?: readonly string[][]
5813
5824
  /**
5814
5825
  * The format the action's prose value is in, when it is not marker text —
5815
5826
  * `'estiva-blocks-1'` for a block document (SPEC §7.3's `format`, MAN-1).
@@ -6079,6 +6090,13 @@ function buildOneActionEvent(args: ActionEventArgs): UnsignedActionEvent | strin
6079
6090
  if (ps.length >= MAX_MENTIONED_PEOPLE) break
6080
6091
  if (!ps.some((t) => t[1] === person)) tags.push(['p', person])
6081
6092
  }
6093
+ // What the body links, as the apps' sends tag it, after the people (§13.1, PEEKM-7).
6094
+ for (const tag of args.linkTags ?? []) {
6095
+ if (!LINK_TAG_NAMES.has(tag[0]) || typeof tag[1] !== 'string') continue
6096
+ if ((tag[0] === 'a' || tag[0] === 'part') && tag[1] === address) continue
6097
+ if (tag[0] === 'q' && tag[1] === replyTo?.id) continue
6098
+ if (!tags.some((t) => t[0] === tag[0] && t[1] === tag[1])) tags.push([...tag])
6099
+ }
6082
6100
  }
6083
6101
  // A move also names its new parent where a relay indexes it (SPEC §7.2, FOL-45):
6084
6102
  // `value` is not indexed, so without this no read by the new parent finds a