@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 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"}