@estiva-app/interop 0.67.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 +56 -0
- package/README.md +19 -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 +34 -1
- package/dist/projection.d.ts.map +1 -1
- package/dist/projection.js +37 -6
- 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 +74 -6
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.
|
|
@@ -4154,8 +4157,14 @@ async function walkArchivedAbove(
|
|
|
4154
4157
|
* every change naming its addresses — titles, statuses, moves — not only the
|
|
4155
4158
|
* archives, and a relay answers newest first, so a small group keeps the
|
|
4156
4159
|
* archive change inside the page.
|
|
4160
|
+
*
|
|
4161
|
+
* Ten, because the relay slows sharply past about twelve values in one `#a`
|
|
4162
|
+
* on `kind:1851`, while many small filters in one request do not. Measured as
|
|
4163
|
+
* the agent on production 2026-10-26, 49 Folder channels with no change among
|
|
4164
|
+
* them: one filter of 49 took 15–20 s, of 25 3.5 s, of 12 0.3 s, and 49
|
|
4165
|
+
* filters of one 0.3–0.5 s (43e9a775). `kind:1111` stayed under a second at 49.
|
|
4157
4166
|
*/
|
|
4158
|
-
const ARCHIVE_READ_GROUP =
|
|
4167
|
+
const ARCHIVE_READ_GROUP = 10
|
|
4159
4168
|
|
|
4160
4169
|
/**
|
|
4161
4170
|
* Identifiers per root filter in {@link resolveParents}. A root read answers
|
|
@@ -5804,6 +5813,14 @@ export interface ActionEventArgs {
|
|
|
5804
5813
|
* why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-reply-on-a-page-keeps-its-threads-place.md
|
|
5805
5814
|
*/
|
|
5806
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[][]
|
|
5807
5824
|
/**
|
|
5808
5825
|
* The format the action's prose value is in, when it is not marker text —
|
|
5809
5826
|
* `'estiva-blocks-1'` for a block document (SPEC §7.3's `format`, MAN-1).
|
|
@@ -6073,6 +6090,13 @@ function buildOneActionEvent(args: ActionEventArgs): UnsignedActionEvent | strin
|
|
|
6073
6090
|
if (ps.length >= MAX_MENTIONED_PEOPLE) break
|
|
6074
6091
|
if (!ps.some((t) => t[1] === person)) tags.push(['p', person])
|
|
6075
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
|
+
}
|
|
6076
6100
|
}
|
|
6077
6101
|
// A move also names its new parent where a relay indexes it (SPEC §7.2, FOL-45):
|
|
6078
6102
|
// `value` is not indexed, so without this no read by the new parent finds a
|
|
@@ -6320,7 +6344,24 @@ export interface FolderContents extends FolderSummary {
|
|
|
6320
6344
|
* goes; a sidebar built by walking something else would inherit exactly that.
|
|
6321
6345
|
* This asks for folders by kind.
|
|
6322
6346
|
*/
|
|
6323
|
-
export async function listFolders(
|
|
6347
|
+
export async function listFolders(
|
|
6348
|
+
query: QueryFn,
|
|
6349
|
+
options: {
|
|
6350
|
+
/**
|
|
6351
|
+
* `false` leaves out what only a record's channel needs — a Ship project's
|
|
6352
|
+
* conversation placed under the Folder that lists the project, and archived
|
|
6353
|
+
* with it — and so reads only the Folders' own archives. Those channels have
|
|
6354
|
+
* no state, so {@link topLevelFolders} is the same either way.
|
|
6355
|
+
*
|
|
6356
|
+
* For a reader that walks Folders for their files and draws no dots (the
|
|
6357
|
+
* agent's Peek topics): placing them reads every change to every file a
|
|
6358
|
+
* Folder lists, and a text save is a whole document. Measured as the agent
|
|
6359
|
+
* on production 2026-10-26: 149 s and 22.8 MB with them, where the Folders'
|
|
6360
|
+
* records alone were 0.9 s.
|
|
6361
|
+
*/
|
|
6362
|
+
recordChannels?: boolean
|
|
6363
|
+
} = {},
|
|
6364
|
+
): Promise<FolderSummary[]> {
|
|
6324
6365
|
const { events, byId } = await readFolderRecords(query)
|
|
6325
6366
|
/*
|
|
6326
6367
|
A folder listed in another folder's state is a file there. Read off the
|
|
@@ -6342,7 +6383,17 @@ export async function listFolders(query: QueryFn): Promise<FolderSummary[]> {
|
|
|
6342
6383
|
listedIn.set(identifier, containers)
|
|
6343
6384
|
}
|
|
6344
6385
|
}
|
|
6345
|
-
const { recordsOf, archives, rootOf } =
|
|
6386
|
+
const { recordsOf, archives, rootOf } =
|
|
6387
|
+
options.recordChannels === false
|
|
6388
|
+
? {
|
|
6389
|
+
recordsOf: new Map<string, string[]>(),
|
|
6390
|
+
archives: await readArchiveChanges(
|
|
6391
|
+
[...byId.values()].flatMap((folder) => (folder.channel ? [folder.channel] : [])),
|
|
6392
|
+
query,
|
|
6393
|
+
),
|
|
6394
|
+
rootOf: new Map<string, SignedEvent>(),
|
|
6395
|
+
}
|
|
6396
|
+
: await placeRecordChannels(events, byId, listedIn, query)
|
|
6346
6397
|
for (const [id, containers] of listedIn) {
|
|
6347
6398
|
const folder = byId.get(id)
|
|
6348
6399
|
if (folder) folder.listedIn = containers
|
|
@@ -6802,6 +6853,17 @@ export async function resolveFolderContents(
|
|
|
6802
6853
|
* card ({@link ArchiveReadOptions.folderFiles}).
|
|
6803
6854
|
*/
|
|
6804
6855
|
listedOnly?: boolean
|
|
6856
|
+
/**
|
|
6857
|
+
* Only the listed files of these kinds: the rest are neither read nor
|
|
6858
|
+
* returned, as if no app drew them. Every rule above still holds for the
|
|
6859
|
+
* ones kept — a parent of another kind is read as a link reads it.
|
|
6860
|
+
*
|
|
6861
|
+
* For a reader that draws only some kinds (the agent's Peek topics: bare
|
|
6862
|
+
* files and nested Folders), since every listed file is read with its whole
|
|
6863
|
+
* change history: Estiva HQ cost 75 s and 11 MB on 2026-10-26, nearly all
|
|
6864
|
+
* of it project descriptions.
|
|
6865
|
+
*/
|
|
6866
|
+
kinds?: readonly number[]
|
|
6805
6867
|
} = {},
|
|
6806
6868
|
): Promise<FolderContents> {
|
|
6807
6869
|
// 1. The folder itself. Both kinds in one trip: the state is the model and
|
|
@@ -6833,7 +6895,7 @@ export async function resolveFolderContents(
|
|
|
6833
6895
|
: {}),
|
|
6834
6896
|
}
|
|
6835
6897
|
|
|
6836
|
-
const { addresses, placed } = state
|
|
6898
|
+
const { addresses: everyAddress, placed } = state
|
|
6837
6899
|
? // §5.2: one tag type lists every file, topics included, with no special
|
|
6838
6900
|
// case. The order is the folder's, so it is preserved rather than sorted.
|
|
6839
6901
|
{
|
|
@@ -6843,6 +6905,10 @@ export async function resolveFolderContents(
|
|
|
6843
6905
|
: options.listedOnly
|
|
6844
6906
|
? { addresses: [], placed: new Map<string, SignedEvent[]>() }
|
|
6845
6907
|
: await addressesByContainment(folder, query)
|
|
6908
|
+
const { kinds } = options
|
|
6909
|
+
const addresses = kinds
|
|
6910
|
+
? everyAddress.filter((address) => kinds.includes(addressPointerOf(address)?.kind ?? NaN))
|
|
6911
|
+
: everyAddress
|
|
6846
6912
|
|
|
6847
6913
|
if (addresses.length === 0) {
|
|
6848
6914
|
// Nothing listed, so no change query to ride on: the Folder's own archive
|
|
@@ -6902,7 +6968,9 @@ export async function resolveFolderContents(
|
|
|
6902
6968
|
// for it here only repeated them: its 500 newest are among each group's page
|
|
6903
6969
|
// (APP-2, where it was most of a second copy of every change).
|
|
6904
6970
|
const otherChangeKinds = changeKinds.filter((kind) => kind !== ARCHIVE_RULE.changeKind)
|
|
6905
|
-
|
|
6971
|
+
// Chunked: at ten addresses per archive filter, a Folder of about 1,200 files
|
|
6972
|
+
// would pass the relay's filters-per-request ceiling in one request.
|
|
6973
|
+
const events = await queryChunked([
|
|
6906
6974
|
...[...groups.values()].map(({ pointer, addresses: group }) => ({
|
|
6907
6975
|
kinds: [pointer.kind],
|
|
6908
6976
|
authors: [pointer.pubkey],
|
|
@@ -6915,7 +6983,7 @@ export async function resolveFolderContents(
|
|
|
6915
6983
|
...archiveFilters(channelAddress ? [...addresses, channelAddress] : addresses),
|
|
6916
6984
|
// A Folder listed here counts its archive only from its own admins (§3.2). Same request.
|
|
6917
6985
|
...(nestedFolderIds.length ? [{ kinds: [KIND_CHANNEL_ADMINS], '#d': nestedFolderIds, limit: nestedFolderIds.length }] : []),
|
|
6918
|
-
])
|
|
6986
|
+
], query)
|
|
6919
6987
|
const ownArchive = folderArchiveOf(events, summary)
|
|
6920
6988
|
if (ownArchive) summary.archived = ownArchive
|
|
6921
6989
|
|