@estiva-app/interop 0.68.0 → 0.69.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/CHANGELOG.md +33 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -0
- package/dist/index.js.map +1 -1
- package/dist/links.d.ts +100 -0
- package/dist/links.d.ts.map +1 -0
- package/dist/links.js +241 -0
- package/dist/links.js.map +1 -0
- package/dist/mentions.d.ts +42 -0
- package/dist/mentions.d.ts.map +1 -0
- package/dist/mentions.js +102 -0
- package/dist/mentions.js.map +1 -0
- package/dist/projection.d.ts +8 -0
- package/dist/projection.d.ts.map +1 -1
- package/dist/projection.js +13 -0
- package/dist/projection.js.map +1 -1
- package/package.json +5 -5
- package/src/index.ts +19 -0
- package/src/links.ts +312 -0
- package/src/mentions.ts +119 -0
- package/src/projection.ts +18 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@estiva-app/interop",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.69.0",
|
|
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.
|
|
51
|
-
"@estiva-app/protocol": ">=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.
|
|
55
|
-
"@estiva-app/protocol": ">=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,25 @@ 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 { mentionedInFilter, mentionedInOf, readMentionedIn, MENTIONED_IN_LIMIT, type MentionedIn } from './mentions.js'
|
|
168
|
+
|
|
150
169
|
/**
|
|
151
170
|
* RFC 0.5 §7's URL grammar — how an object is named in an address bar, and how
|
|
152
171
|
* 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
|
+
}
|
package/src/mentions.ts
ADDED
|
@@ -0,0 +1,119 @@
|
|
|
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, 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
|
+
/** The one filter for the candidates: every message, comment and edit pointing at the file. */
|
|
37
|
+
export function mentionedInFilter(address: string, limit = MENTIONED_IN_LIMIT): Record<string, unknown> {
|
|
38
|
+
return { kinds: [KIND_COMMENT, KIND_MESSAGE, KIND_EDIT], '#a': [address], limit }
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
const isMessage = (event: SignedEvent) => event.kind === KIND_COMMENT || event.kind === KIND_MESSAGE
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* The messages among `events` that list under the file, newest first.
|
|
45
|
+
*
|
|
46
|
+
* `events` holds the candidates ({@link mentionedInFilter}), the messages their
|
|
47
|
+
* edits edit, and every edit of each message; `resolveLink` what the app links
|
|
48
|
+
* in their words name. `commentKinds` is the file's owner's comment kinds
|
|
49
|
+
* (`isCommentOn`): a message on the file itself is not a mention of it.
|
|
50
|
+
* `unanswered` says which links could not be asked about: a message whose
|
|
51
|
+
* latest version points at the file and holds one keeps its row until the
|
|
52
|
+
* link can be read, rather than lose it to a failed read.
|
|
53
|
+
*/
|
|
54
|
+
export function mentionedInOf(
|
|
55
|
+
events: readonly SignedEvent[],
|
|
56
|
+
address: string,
|
|
57
|
+
resolveLink?: LinkResolver,
|
|
58
|
+
commentKinds?: readonly number[],
|
|
59
|
+
unanswered: (url: string) => boolean = () => false,
|
|
60
|
+
): MentionedIn[] {
|
|
61
|
+
const messages = new Map<string, SignedEvent>()
|
|
62
|
+
for (const event of events) if (isMessage(event)) messages.set(event.id.toLowerCase(), event)
|
|
63
|
+
const edits = editsByTarget(events)
|
|
64
|
+
const pointed = new Set<string>()
|
|
65
|
+
for (const event of events) {
|
|
66
|
+
if (!event.tags.some((t) => t[0] === 'a' && t[1] === address)) continue
|
|
67
|
+
const id = event.kind === KIND_EDIT ? editTargetOf(event) : isMessage(event) ? event.id.toLowerCase() : undefined
|
|
68
|
+
if (id) pointed.add(id)
|
|
69
|
+
}
|
|
70
|
+
const file = valueOf(address)
|
|
71
|
+
const out: MentionedIn[] = []
|
|
72
|
+
for (const id of pointed) {
|
|
73
|
+
const event = messages.get(id)
|
|
74
|
+
if (!event) continue
|
|
75
|
+
if (anchorsOf(event).includes(address) || isCommentOn(event, address, commentKinds)) continue
|
|
76
|
+
// An edit by anyone but the author is not the message's (the relay refuses one; a reader does not trust that).
|
|
77
|
+
const edit = edits.get(id)?.filter((e) => e.pubkey === event.pubkey).at(-1)
|
|
78
|
+
const body = edit?.content ?? event.content
|
|
79
|
+
const tree = toRenderTree(body, 'marker')
|
|
80
|
+
const pointsNow = (edit ?? event).tags.some((t) => t[0] === 'a' && t[1] === address)
|
|
81
|
+
if (!valuesIn(tree, resolveLink).includes(file) && !(pointsNow && linksIn(tree).some(unanswered))) continue
|
|
82
|
+
out.push(edit ? { event, body, edit } : { event, body })
|
|
83
|
+
}
|
|
84
|
+
return out.sort((a, b) => b.event.created_at - a.event.created_at)
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* {@link mentionedInOf} as the viewer: the candidates, then the messages their
|
|
89
|
+
* edits edit and every edit of each message, then what the links in their
|
|
90
|
+
* latest words name, asked through `links` and waited for at most `waitMs`.
|
|
91
|
+
* Throws when a read is refused, so an unreadable relay and a file nobody
|
|
92
|
+
* mentions are not the same empty list.
|
|
93
|
+
*/
|
|
94
|
+
export async function readMentionedIn(
|
|
95
|
+
query: QueryFn,
|
|
96
|
+
address: string,
|
|
97
|
+
options: { links?: LinkReader; limit?: number; waitMs?: number; commentKinds?: readonly number[] } = {},
|
|
98
|
+
): Promise<MentionedIn[]> {
|
|
99
|
+
const candidates = await query([mentionedInFilter(address, options.limit)])
|
|
100
|
+
const held = new Set(candidates.filter(isMessage).map((e) => e.id.toLowerCase()))
|
|
101
|
+
const missing = [...new Set(candidates.filter((e) => e.kind === KIND_EDIT).map(editTargetOf))].filter((id): id is string => !!id && !held.has(id))
|
|
102
|
+
const targets = missing.length ? await query([{ ids: missing, kinds: [KIND_COMMENT, KIND_MESSAGE] }]) : []
|
|
103
|
+
const ids = [...held, ...targets.map((e) => e.id.toLowerCase())]
|
|
104
|
+
const edits = ids.length ? await query([{ kinds: [KIND_EDIT], '#e': ids, limit: 1000 }]) : []
|
|
105
|
+
const events = [...candidates, ...targets, ...edits]
|
|
106
|
+
const links = options.links
|
|
107
|
+
if (!links) return mentionedInOf(events, address, undefined, options.commentKinds, () => true)
|
|
108
|
+
// Every link in a candidate's latest words: read as if each named the file, so each candidate holding one is kept to ask.
|
|
109
|
+
const urls = [...new Set(mentionedInOf(events, address, () => address, options.commentKinds).flatMap((m) => linksIn(toRenderTree(m.body, 'marker'))))]
|
|
110
|
+
const waiting = urls.filter((url) => !links.answered(url))
|
|
111
|
+
if (waiting.length) await within(links.ask(waiting), options.waitMs ?? 5000)
|
|
112
|
+
return mentionedInOf(events, address, links.known, options.commentKinds, (url) => !links.answered(url))
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/** The address as `valuesIn` spells it. */
|
|
116
|
+
function valueOf(address: string): string {
|
|
117
|
+
const [kind, pubkey = '', ...d] = address.split(':')
|
|
118
|
+
return `${kind}:${pubkey.toLowerCase()}:${d.join(':')}`
|
|
119
|
+
}
|
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
|