@estiva-app/interop 0.89.0 → 0.91.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 +46 -0
- package/dist/activity.d.ts +134 -0
- package/dist/activity.d.ts.map +1 -0
- package/dist/activity.js +497 -0
- package/dist/activity.js.map +1 -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/listedConversations.d.ts +18 -9
- package/dist/listedConversations.d.ts.map +1 -1
- package/dist/listedConversations.js +24 -10
- package/dist/listedConversations.js.map +1 -1
- package/dist/liveAsStored.d.ts +30 -0
- package/dist/liveAsStored.d.ts.map +1 -0
- package/dist/liveAsStored.js +43 -0
- package/dist/liveAsStored.js.map +1 -0
- package/dist/topics.d.ts +12 -0
- package/dist/topics.d.ts.map +1 -1
- package/dist/topics.js +3 -3
- package/dist/topics.js.map +1 -1
- package/package.json +1 -1
- package/src/activity.ts +527 -0
- package/src/index.ts +19 -0
- package/src/listedConversations.ts +31 -11
- package/src/liveAsStored.ts +46 -0
- package/src/topics.ts +5 -3
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,52 @@ how a declaration is read, is a MAJOR — in `0.x`, a MINOR — even when no
|
|
|
6
6
|
TypeScript signature moved. A consumer upgrading must be able to tell whether
|
|
7
7
|
manifests already published still mean what they meant.
|
|
8
8
|
|
|
9
|
+
## 0.91.0 — 2026-11-09
|
|
10
|
+
|
|
11
|
+
**Manifest: nothing new. Wire: the live watches' REQs name no team on a relay that says it delivers by file; nothing written** (TOPI-12, SPEC §5).
|
|
12
|
+
|
|
13
|
+
- `relayNamesTeams(relay)`: from the relay's NIP-11 (`Relay.info()`, read
|
|
14
|
+
once per relay object), whether a live watch must name teams: false only
|
|
15
|
+
when it lists `buzz-live-as-stored`, as ours has since 9 Nov; true for any
|
|
16
|
+
other relay, or one that does not answer. `namesTeamsOn(info)` is the same
|
|
17
|
+
rule on a document already read; `LIVE_AS_STORED_EXTENSION` the name.
|
|
18
|
+
- `watchListedConversations` and `watchTopicActivity` take
|
|
19
|
+
`namesTeams: relayNamesTeams(relay)`, a promise: the watch opens once it
|
|
20
|
+
settles (`since` covers the wait) and asks by file alone on such a relay,
|
|
21
|
+
one set of filters instead of one per 128 teams. Without it they name
|
|
22
|
+
teams, as before (record a-request-kept-open-hears-what-asking-again-would-return:
|
|
23
|
+
an app stops naming teams only on a relay that says so).
|
|
24
|
+
- Upgrading: pass `namesTeams: relayNamesTeams(httpRelay)` to stop naming
|
|
25
|
+
teams on our relay.
|
|
26
|
+
|
|
27
|
+
## 0.90.0 — 2026-11-09
|
|
28
|
+
|
|
29
|
+
**Manifest: nothing new. Wire: reads only, nothing written; existing events read the existing way** (TOPI-10).
|
|
30
|
+
|
|
31
|
+
- `readTopicActivity(query, topics)`: each topic's newest activity, the one
|
|
32
|
+
rule Peek, Ship and Leaf order topics by (Miky, 6 Nov: "where anything
|
|
33
|
+
moved"). A message in the topic's conversation; a change to the topic
|
|
34
|
+
except tidying it (`order:`, `look:`, a file taken off); a change
|
|
35
|
+
to, comment on or new file under any file it lists, any depth (a project's
|
|
36
|
+
issues, a document's pages; the newest 500 under each parent). Never a
|
|
37
|
+
rename (`title`, on any file; Miky, 9 Nov), `member:`/`follow:` or read
|
|
38
|
+
state. An event counts only on the file the fold reads it on, never by a
|
|
39
|
+
tag alone: a change by its first `a`, its `O`, and its file's own team in
|
|
40
|
+
`h`; a comment by its root, never a crossed one; a new file by its one
|
|
41
|
+
`a` (security review: anybody may tag any file). Each
|
|
42
|
+
time capped at the reader's clock. Takes any set of topics, so an Explore
|
|
43
|
+
page orders every topic the reader can open the same way
|
|
44
|
+
(`activityTopics(read.topics)` from `readTopics`).
|
|
45
|
+
- `watchTopicActivity(relay, activity, onActivity)`: keeps it current live,
|
|
46
|
+
in one REQ, naming the teams as `watchListedConversations` does; a new
|
|
47
|
+
issue in a listed project is heard and listened to from then on.
|
|
48
|
+
- `countsAsActivity(event, topic)` and `byActivity(at)`: the rule event by
|
|
49
|
+
event, and the order.
|
|
50
|
+
- Cost, measured 9 Nov on production as the agent: 2.0 MB in 7 requests,
|
|
51
|
+
about 2 s, for Miky's 22 topics and for all 47 alike. Most of it is a
|
|
52
|
+
file's newest text save (whole text) and the roots of issues under listed
|
|
53
|
+
projects.
|
|
54
|
+
|
|
9
55
|
## 0.89.0 — 2026-11-09
|
|
10
56
|
|
|
11
57
|
**Manifest: nothing new. Wire: reads only, nothing written; `readTopics` can walk archived parents by the list read** (SPEC §6.13, ALO-15).
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Your topics, newest activity first: the one shared rule Peek, Ship and Leaf
|
|
3
|
+
* order topics by (TOPI-10; Miky, 2026-11-06, "Where anything moved").
|
|
4
|
+
*
|
|
5
|
+
* A topic's time is when anything last happened in it, deep:
|
|
6
|
+
*
|
|
7
|
+
* - a message or reply in its own conversation (`kind:1111`/`9` with its `A`);
|
|
8
|
+
* - a change to the topic itself, except tidying it: its `order:<d>` and
|
|
9
|
+
* `look:<d>` (arranging, a row/card switch), a file taken off its list
|
|
10
|
+
* (`lists:<d>` = `false`) — a file put on it counts;
|
|
11
|
+
* - a change to, or a comment on, any file its list holds, and on every file
|
|
12
|
+
* under one: a listed project's issues, a listed document's pages, any depth
|
|
13
|
+
* (the newest {@link MAX_CHILDREN} under each);
|
|
14
|
+
* - a new file under one (an issue filed in a listed project).
|
|
15
|
+
*
|
|
16
|
+
* Never, anywhere: a rename (`title`, on the topic or any file; Miky,
|
|
17
|
+
* 2026-11-09), who is on a file or at what level (`member:<P>`, `follow:<P>`,
|
|
18
|
+
* §11.8) — joining would move a topic up for everyone — and read state
|
|
19
|
+
* (`kind:30078`). The agent's own writes count like anyone's.
|
|
20
|
+
*
|
|
21
|
+
* An event counts only on the file it is on as the fold reads it, never by a
|
|
22
|
+
* tag alone: a change by its first `a`, in its file's own team (`h`); a
|
|
23
|
+
* comment by its root, never a crossed one; a new file by its one `a`.
|
|
24
|
+
* With nothing else, a topic's time is its first record's.
|
|
25
|
+
*
|
|
26
|
+
* Every `created_at` is the author's to write, and the relay takes one up to
|
|
27
|
+
* 15 minutes ahead: each time is capped at the reader's clock, so a
|
|
28
|
+
* future-dated event cannot pin a topic to the top.
|
|
29
|
+
*
|
|
30
|
+
* Two people's orders may differ where a listed file sits in a team only one
|
|
31
|
+
* of them reads; nothing unreadable is revealed, since each reads as itself.
|
|
32
|
+
*
|
|
33
|
+
* The rule takes any set of topics, so an Explore page orders every topic the
|
|
34
|
+
* reader can open with the same read ({@link readTopicActivity}), and a live
|
|
35
|
+
* app keeps it current with {@link watchTopicActivity}.
|
|
36
|
+
* why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/each-file-on-a-topic-keeps-its-own-place-and-look.md
|
|
37
|
+
*/
|
|
38
|
+
import { type LiveRelay, type SignedEvent } from '@estiva-app/protocol';
|
|
39
|
+
import { type QueryFn } from './projection.js';
|
|
40
|
+
import { type ReadTopic } from './topics.js';
|
|
41
|
+
/** A file whose activity is a topic's: on its list, or under a file on it. */
|
|
42
|
+
export interface ActivityFile {
|
|
43
|
+
/** Its address, `<kind>:<pubkey>:<d>`. */
|
|
44
|
+
address: string;
|
|
45
|
+
/** Its team, from its root (§6.2), when the reader holds it: a live watch names it. */
|
|
46
|
+
folder: string | null;
|
|
47
|
+
}
|
|
48
|
+
/** A topic to order, as the reader holds it. */
|
|
49
|
+
export interface ActivityTopic {
|
|
50
|
+
/** Its address. */
|
|
51
|
+
address: string;
|
|
52
|
+
/** Its first record's time (Unix seconds): its time, when nothing has happened in it since. */
|
|
53
|
+
createdAt?: number;
|
|
54
|
+
/** Its team, from its root: a change to it counts only in it, and a live watch names it. */
|
|
55
|
+
folder?: string | null;
|
|
56
|
+
/** The files its list holds. A file under one of them is found by the read. */
|
|
57
|
+
files: readonly ActivityFile[];
|
|
58
|
+
}
|
|
59
|
+
/** {@link readTopicActivity}'s answer, and what {@link watchTopicActivity} keeps current. */
|
|
60
|
+
export interface TopicActivity {
|
|
61
|
+
/** Each topic asked for, by address: Unix seconds of the newest thing that happened in it, capped at the reader's clock; 0 when nothing is known. */
|
|
62
|
+
at: Map<string, number>;
|
|
63
|
+
/** Each topic's files, by address: the listed ones and every file under them. */
|
|
64
|
+
files: Map<string, ActivityFile[]>;
|
|
65
|
+
/** Each topic's team, as asked. */
|
|
66
|
+
folders: Map<string, string | null>;
|
|
67
|
+
}
|
|
68
|
+
/** {@link ActivityTopic}s from {@link readTopics}' answer: each topic with its resolved list. */
|
|
69
|
+
export declare function activityTopics(topics: readonly ReadTopic[]): ActivityTopic[];
|
|
70
|
+
/**
|
|
71
|
+
* Whether an event is news for the topic it is read for: the rule above,
|
|
72
|
+
* event by event. `topic` is the address of the topic being ordered, so a
|
|
73
|
+
* change to the topic itself is judged as tidying or not.
|
|
74
|
+
*/
|
|
75
|
+
export declare function countsAsActivity(event: SignedEvent, topic: string): boolean;
|
|
76
|
+
/** Newest first, then by address: the order of a set of topics, from {@link TopicActivity.at}. */
|
|
77
|
+
export declare function byActivity(at: ReadonlyMap<string, number>): (a: string, b: string) => number;
|
|
78
|
+
/**
|
|
79
|
+
* Each topic's newest activity (the rule above), for any set of topics the
|
|
80
|
+
* reader holds — theirs, or every one they can open.
|
|
81
|
+
*
|
|
82
|
+
* Reads, whatever the number of topics: one request per level of files under
|
|
83
|
+
* the listed ones (a project's issues, then each further level of pages),
|
|
84
|
+
* then the newest few events of each topic's conversation and own changes and
|
|
85
|
+
* of each file's changes and comments, every target one filter in the same
|
|
86
|
+
* request (another per {@link MAX_FILTERS_PER_QUERY}). A target whose newest
|
|
87
|
+
* events are all tidying is asked again from older ones, up to a few rounds.
|
|
88
|
+
*
|
|
89
|
+
* Measured 9 Nov 2026 on production over the 47 topics the agent can read
|
|
90
|
+
* (Miky is in 24 of them): about 1.9 MB in 7 requests, 1 s. Most of it is the
|
|
91
|
+
* newest text save of a file, which carries the whole text, and the roots of
|
|
92
|
+
* the issues under listed projects.
|
|
93
|
+
*
|
|
94
|
+
* `query` answers each filter as one request would, honouring `limit` and
|
|
95
|
+
* `until` (the apps' viewer query does). A failed read rejects.
|
|
96
|
+
*/
|
|
97
|
+
export declare function readTopicActivity(query: QueryFn, topics: readonly ActivityTopic[], options?: {
|
|
98
|
+
nowSeconds?: number;
|
|
99
|
+
}): Promise<TopicActivity>;
|
|
100
|
+
/** A live watch's handle. */
|
|
101
|
+
export interface ActivityWatch {
|
|
102
|
+
/** Idempotent. Closes its subscriptions. */
|
|
103
|
+
stop(): void;
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* Keep {@link TopicActivity} current, live: hear every new event that is news
|
|
107
|
+
* for a topic it holds (the rule above), raise that topic's time, and say so.
|
|
108
|
+
* A new file under a listed one (an issue filed in a listed project) is news,
|
|
109
|
+
* and its own activity is heard from then on.
|
|
110
|
+
*
|
|
111
|
+
* One REQ for every topic (another per {@link MAX_FILTERS_PER_REQ} filters).
|
|
112
|
+
* `onActivity` is called with the topic and its new time, after `activity.at`
|
|
113
|
+
* is raised in place; an event that is not news, or older than what is held,
|
|
114
|
+
* says nothing.
|
|
115
|
+
*
|
|
116
|
+
* As {@link watchListedConversations} does, it asks by file alone when given
|
|
117
|
+
* `namesTeams: relayNamesTeams(relay)` on a relay that lists
|
|
118
|
+
* `buzz-live-as-stored` (ours), opening once that answer is in. Otherwise
|
|
119
|
+
* (the default) every filter also names the teams of the topics and their
|
|
120
|
+
* files, and a file whose team is unknown is not heard from its team.
|
|
121
|
+
*
|
|
122
|
+
* why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-request-kept-open-hears-what-asking-again-would-return.md
|
|
123
|
+
*/
|
|
124
|
+
export declare function watchTopicActivity(relay: Pick<LiveRelay, 'subscribe'>, activity: TopicActivity, onActivity: (topic: string, at: number) => void, options?: {
|
|
125
|
+
/** Unix seconds to hear from. Defaults to now. */
|
|
126
|
+
since?: number;
|
|
127
|
+
/** Whether to name teams; a promise ({@link relayNamesTeams}) holds the REQ until it settles. Defaults to true. */
|
|
128
|
+
namesTeams?: boolean | Promise<boolean>;
|
|
129
|
+
onClosed?: (reason: string) => void;
|
|
130
|
+
now?: () => number;
|
|
131
|
+
setTimer?: (run: () => void, ms: number) => unknown;
|
|
132
|
+
clearTimer?: (timer: unknown) => void;
|
|
133
|
+
}): ActivityWatch;
|
|
134
|
+
//# sourceMappingURL=activity.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAmC,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAExG,OAAO,EAA0B,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAA;AACtE,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,aAAa,CAAA;AAwB9D,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,uFAAuF;IACvF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B,mBAAmB;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,+EAA+E;IAC/E,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CAC/B;AAED,6FAA6F;AAC7F,MAAM,WAAW,aAAa;IAC5B,qJAAqJ;IACrJ,EAAE,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACvB,iFAAiF;IACjF,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAA;IAClC,mCAAmC;IACnC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAA;CACpC;AAED,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,aAAa,EAAE,CAO5E;AAaD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAa3E;AAED,kGAAkG;AAClG,wBAAgB,UAAU,CAAC,EAAE,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAE5F;AA+FD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACpC,OAAO,CAAC,aAAa,CAAC,CAoGxB;AAED,6BAA6B;AAC7B,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,IAAI,IAAI,IAAI,CAAA;CACb;AAQD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,EACnC,QAAQ,EAAE,aAAa,EACvB,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,EAC/C,OAAO,GAAE;IACP,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mHAAmH;IACnH,UAAU,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACvC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IACnC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAA;IACnD,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CACjC,GACL,aAAa,CA2Hf"}
|