@estiva-app/interop 0.88.0 → 0.90.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,48 @@ 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.90.0 — 2026-11-09
10
+
11
+ **Manifest: nothing new. Wire: reads only, nothing written; existing events read the existing way** (TOPI-10).
12
+
13
+ - `readTopicActivity(query, topics)`: each topic's newest activity, the one
14
+ rule Peek, Ship and Leaf order topics by (Miky, 6 Nov: "where anything
15
+ moved"). A message in the topic's conversation; a change to the topic
16
+ except tidying it (`order:`, `look:`, a file taken off); a change
17
+ to, comment on or new file under any file it lists, any depth (a project's
18
+ issues, a document's pages; the newest 500 under each parent). Never a
19
+ rename (`title`, on any file; Miky, 9 Nov), `member:`/`follow:` or read
20
+ state. An event counts only on the file the fold reads it on, never by a
21
+ tag alone: a change by its first `a`, its `O`, and its file's own team in
22
+ `h`; a comment by its root, never a crossed one; a new file by its one
23
+ `a` (security review: anybody may tag any file). Each
24
+ time capped at the reader's clock. Takes any set of topics, so an Explore
25
+ page orders every topic the reader can open the same way
26
+ (`activityTopics(read.topics)` from `readTopics`).
27
+ - `watchTopicActivity(relay, activity, onActivity)`: keeps it current live,
28
+ in one REQ, naming the teams as `watchListedConversations` does; a new
29
+ issue in a listed project is heard and listened to from then on.
30
+ - `countsAsActivity(event, topic)` and `byActivity(at)`: the rule event by
31
+ event, and the order.
32
+ - Cost, measured 9 Nov on production as the agent: 2.0 MB in 7 requests,
33
+ about 2 s, for Miky's 22 topics and for all 47 alike. Most of it is a
34
+ file's newest text save (whole text) and the roots of issues under listed
35
+ projects.
36
+
37
+ ## 0.89.0 — 2026-11-09
38
+
39
+ **Manifest: nothing new. Wire: reads only, nothing written; `readTopics` can walk archived parents by the list read** (SPEC §6.13, ALO-15).
40
+
41
+ - `readTopics` takes `{ parentsListRead: true }`: the parents it walks to see whether
42
+ a topic is archived with one (a topic's project) are read as their first
43
+ record and their fields' current changes, never every change by `#a`, with
44
+ 0.88.0's fallback for one the list read leaves out. The topics themselves are
45
+ read as before, their text included (`listRead` stays free for when they
46
+ switch). Pass it as soon as NIP-11 advertises `file_list.newest`.
47
+ - `resolveForeignRoots` gains `parentsListRead`: with `archivedWith`, only the
48
+ parents walked for an archive go by the list read.
49
+ - Without either option every read is as before.
50
+
9
51
  ## 0.88.0 — 2026-11-06
10
52
 
11
53
  **Manifest: nothing new. Wire: reads only, nothing written; the list read (SPEC §6.13) now also answers parents and archived parents** (ALO-15).
@@ -0,0 +1,131 @@
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, every filter also names the teams
117
+ * of the topics and their files (`namesTeams`, on by default), since our
118
+ * relay does not yet deliver a team's event live to a subscription that names
119
+ * no team. A file whose team is unknown is still asked for; it is heard once
120
+ * the relay delivers by file.
121
+ */
122
+ export declare function watchTopicActivity(relay: Pick<LiveRelay, 'subscribe'>, activity: TopicActivity, onActivity: (topic: string, at: number) => void, options?: {
123
+ /** Unix seconds to hear from. Defaults to now. */
124
+ since?: number;
125
+ namesTeams?: boolean;
126
+ onClosed?: (reason: string) => void;
127
+ now?: () => number;
128
+ setTimer?: (run: () => void, ms: number) => unknown;
129
+ clearTimer?: (timer: unknown) => void;
130
+ }): ActivityWatch;
131
+ //# 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;;;;;;;;;;;;;;;;GAgBG;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,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,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"}