@ghostlytools/sdk 0.0.0-stage → 1.2.3

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.
Files changed (145) hide show
  1. package/README.md +13 -2
  2. package/dist/app.js +67 -0
  3. package/dist/app.js.map +1 -0
  4. package/dist/core.js +207 -0
  5. package/dist/core.js.map +1 -0
  6. package/dist/fakes-CBIuqo5e.js +536 -0
  7. package/dist/fakes-CBIuqo5e.js.map +1 -0
  8. package/dist/fakes.js +2 -0
  9. package/dist/index.js +179 -0
  10. package/dist/index.js.map +1 -0
  11. package/dist/keet-identity-key-BylxCPl4.js +76483 -0
  12. package/dist/keet-identity-key-BylxCPl4.js.map +1 -0
  13. package/dist/src-DCeLPsi-.js +31056 -0
  14. package/dist/src-DCeLPsi-.js.map +1 -0
  15. package/dist/testing.js +330 -0
  16. package/dist/testing.js.map +1 -0
  17. package/dist/types/browser/src/engine/paymentAdapters/providers/contractSuite.d.ts +41 -0
  18. package/dist/types/browser/src/engine/paymentAdapters/providers/lightning.d.ts +103 -0
  19. package/dist/types/browser/src/engine/paymentAdapters/providers/onchain.d.ts +88 -0
  20. package/dist/types/browser/src/engine/paymentAdapters/providers/testing.d.ts +89 -0
  21. package/dist/types/browser/src/engine/paymentAdapters/providers/types.d.ts +151 -0
  22. package/dist/types/browser/src/plugins/bundled.d.ts +8 -0
  23. package/dist/types/browser/src/plugins/registry.d.ts +57 -0
  24. package/dist/types/browser/src/proofs/contract.d.ts +262 -0
  25. package/dist/types/browser/src/proofs/contractSuite.d.ts +27 -0
  26. package/dist/types/browser/src/proofs/testing.d.ts +36 -0
  27. package/dist/types/browser/src/proofs/verify.d.ts +23 -0
  28. package/dist/types/browser/src/shared/mints.d.ts +50 -0
  29. package/dist/types/core/src/appBundle.d.ts +173 -0
  30. package/dist/types/core/src/appStatements.d.ts +142 -0
  31. package/dist/types/core/src/appStore.d.ts +133 -0
  32. package/dist/types/core/src/appUpdates.d.ts +88 -0
  33. package/dist/types/core/src/atprotoIdentity.d.ts +49 -0
  34. package/dist/types/core/src/atprotoRepo.d.ts +101 -0
  35. package/dist/types/core/src/avatar.d.ts +19 -0
  36. package/dist/types/core/src/bip322.d.ts +57 -0
  37. package/dist/types/core/src/bitcoinAddress.d.ts +5 -0
  38. package/dist/types/core/src/bitcoinMessage.d.ts +15 -0
  39. package/dist/types/core/src/bitcoinScript.d.ts +69 -0
  40. package/dist/types/core/src/bolt11.d.ts +30 -0
  41. package/dist/types/core/src/bytes.d.ts +11 -0
  42. package/dist/types/core/src/callSignal.d.ts +232 -0
  43. package/dist/types/core/src/canonicalJson.d.ts +22 -0
  44. package/dist/types/core/src/capsRecord.d.ts +234 -0
  45. package/dist/types/core/src/catchUp.d.ts +45 -0
  46. package/dist/types/core/src/chatFiles.d.ts +271 -0
  47. package/dist/types/core/src/clockWatch.d.ts +72 -0
  48. package/dist/types/core/src/communityRendezvous.d.ts +113 -0
  49. package/dist/types/core/src/crypto.d.ts +10 -0
  50. package/dist/types/core/src/datalink.d.ts +187 -0
  51. package/dist/types/core/src/deviceInvite.d.ts +51 -0
  52. package/dist/types/core/src/deviceLink.d.ts +70 -0
  53. package/dist/types/core/src/dhtDelivery.d.ts +403 -0
  54. package/dist/types/core/src/dhtFiles.d.ts +46 -0
  55. package/dist/types/core/src/did.d.ts +134 -0
  56. package/dist/types/core/src/didDht.d.ts +155 -0
  57. package/dist/types/core/src/directPath.d.ts +63 -0
  58. package/dist/types/core/src/dns.d.ts +41 -0
  59. package/dist/types/core/src/domainProofs.d.ts +88 -0
  60. package/dist/types/core/src/engineErrors.d.ts +90 -0
  61. package/dist/types/core/src/enroll.d.ts +98 -0
  62. package/dist/types/core/src/files.d.ts +73 -0
  63. package/dist/types/core/src/forwards.d.ts +12 -0
  64. package/dist/types/core/src/frames.d.ts +211 -0
  65. package/dist/types/core/src/ghostlink.d.ts +1510 -0
  66. package/dist/types/core/src/groupCommits.d.ts +103 -0
  67. package/dist/types/core/src/groupCommunity.d.ts +714 -0
  68. package/dist/types/core/src/groupCrypto.d.ts +60 -0
  69. package/dist/types/core/src/groupEdits.d.ts +67 -0
  70. package/dist/types/core/src/groupEntry.d.ts +61 -0
  71. package/dist/types/core/src/groupFiles.d.ts +106 -0
  72. package/dist/types/core/src/groupHubs.d.ts +61 -0
  73. package/dist/types/core/src/groupMentions.d.ts +27 -0
  74. package/dist/types/core/src/groupMeta.d.ts +162 -0
  75. package/dist/types/core/src/groupSession.d.ts +710 -0
  76. package/dist/types/core/src/groupSignals.d.ts +167 -0
  77. package/dist/types/core/src/groupTyping.d.ts +56 -0
  78. package/dist/types/core/src/groupWake.d.ts +68 -0
  79. package/dist/types/core/src/handoff.d.ts +255 -0
  80. package/dist/types/core/src/http.d.ts +125 -0
  81. package/dist/types/core/src/identity.d.ts +17 -0
  82. package/dist/types/core/src/identityProofs.d.ts +243 -0
  83. package/dist/types/core/src/identityTimeline.d.ts +72 -0
  84. package/dist/types/core/src/image.d.ts +33 -0
  85. package/dist/types/core/src/index.d.ts +100 -0
  86. package/dist/types/core/src/invite.d.ts +128 -0
  87. package/dist/types/core/src/link.d.ts +353 -0
  88. package/dist/types/core/src/linkPreview.d.ts +60 -0
  89. package/dist/types/core/src/linkTrace.d.ts +12 -0
  90. package/dist/types/core/src/lnurl.d.ts +99 -0
  91. package/dist/types/core/src/messageTime.d.ts +28 -0
  92. package/dist/types/core/src/miniApp.d.ts +141 -0
  93. package/dist/types/core/src/pairedApps.d.ts +151 -0
  94. package/dist/types/core/src/pairedCalls.d.ts +59 -0
  95. package/dist/types/core/src/pairedCapabilities.d.ts +101 -0
  96. package/dist/types/core/src/pairedEdits.d.ts +83 -0
  97. package/dist/types/core/src/pairedFiles.d.ts +30 -0
  98. package/dist/types/core/src/pairedHttp.d.ts +15 -0
  99. package/dist/types/core/src/pairedSession.d.ts +163 -0
  100. package/dist/types/core/src/pairedSignal.d.ts +17 -0
  101. package/dist/types/core/src/pairedTransports.d.ts +76 -0
  102. package/dist/types/core/src/pairedTyping.d.ts +130 -0
  103. package/dist/types/core/src/pairedWake.d.ts +109 -0
  104. package/dist/types/core/src/pairingProgress.d.ts +107 -0
  105. package/dist/types/core/src/paymentIntent.d.ts +111 -0
  106. package/dist/types/core/src/paymentUri.d.ts +34 -0
  107. package/dist/types/core/src/payments.d.ts +97 -0
  108. package/dist/types/core/src/peerProofs.d.ts +98 -0
  109. package/dist/types/core/src/pins.d.ts +73 -0
  110. package/dist/types/core/src/pkarr.d.ts +48 -0
  111. package/dist/types/core/src/pkdns.d.ts +35 -0
  112. package/dist/types/core/src/pubkyProofs.d.ts +25 -0
  113. package/dist/types/core/src/pubkyRing.d.ts +21 -0
  114. package/dist/types/core/src/reactions.d.ts +108 -0
  115. package/dist/types/core/src/records.d.ts +89 -0
  116. package/dist/types/core/src/relay.d.ts +437 -0
  117. package/dist/types/core/src/relayBreaker.d.ts +99 -0
  118. package/dist/types/core/src/replies.d.ts +41 -0
  119. package/dist/types/core/src/services.d.ts +35 -0
  120. package/dist/types/core/src/setUpdate.d.ts +53 -0
  121. package/dist/types/core/src/signal.d.ts +53 -0
  122. package/dist/types/core/src/signer.d.ts +13 -0
  123. package/dist/types/core/src/sparkAddress.d.ts +37 -0
  124. package/dist/types/core/src/sshsig.d.ts +74 -0
  125. package/dist/types/core/src/statusCards.d.ts +253 -0
  126. package/dist/types/core/src/storeForward.d.ts +144 -0
  127. package/dist/types/core/src/text.d.ts +20 -0
  128. package/dist/types/core/src/transport.d.ts +151 -0
  129. package/dist/types/core/src/transportSwitch.d.ts +160 -0
  130. package/dist/types/core/src/turnRead.d.ts +145 -0
  131. package/dist/types/core/src/turnRecord.d.ts +165 -0
  132. package/dist/types/core/src/version.d.ts +9 -0
  133. package/dist/types/core/src/video.d.ts +44 -0
  134. package/dist/types/core/src/voice.d.ts +88 -0
  135. package/dist/types/core/src/webPush.d.ts +58 -0
  136. package/dist/types/sdk/src/app.d.ts +23 -0
  137. package/dist/types/sdk/src/core.d.ts +7 -0
  138. package/dist/types/sdk/src/fakes.d.ts +6 -0
  139. package/dist/types/sdk/src/index.d.ts +26 -0
  140. package/dist/types/sdk/src/testing.d.ts +7 -0
  141. package/dist/types-DvtCy3WB.js +99 -0
  142. package/dist/types-DvtCy3WB.js.map +1 -0
  143. package/dist/verify-DBGw6wYt.js +106 -0
  144. package/dist/verify-DBGw6wYt.js.map +1 -0
  145. package/package.json +70 -4
@@ -0,0 +1,710 @@
1
+ import { GROUP_PROFILE, type SealedSecret } from "./groupCrypto.js";
2
+ import { type GroupCommit, type GroupRole, type Roster } from "./groupCommits.js";
3
+ import { type GroupMeta, type GroupMetaChange, type GroupMetaFrame } from "./groupMeta.js";
4
+ import { type GroupMention } from "./groupMentions.js";
5
+ import { type WireReply } from "./replies.js";
6
+ import { type StatusCard } from "./statusCards.js";
7
+ import { type GroupIncomingEdit } from "./groupEdits.js";
8
+ import { type MeshHubPolicy } from "./groupHubs.js";
9
+ import { type WireReaction } from "./reactions.js";
10
+ import { GROUP_PIN_FRAME, type WirePin } from "./pins.js";
11
+ import { type CatchUpHandled } from "./catchUp.js";
12
+ import { type GroupFileMeta } from "./groupFiles.js";
13
+ /**
14
+ * One member's view of a `group-mesh/1` group: the membership chain, the epoch
15
+ * secrets it was given, its own bounded log of sent messages and what it has
16
+ * seen from each sender. It is transport-agnostic: frames go out through
17
+ * `send(to, frame)` and come in through `handle(from, frame)`, where `to` and
18
+ * `from` are member keys the caller has authenticated (the pairwise edge of
19
+ * the group is pinned to them). Admission frames travel on the inviter's
20
+ * contact link and are handled by `admit`, `join` and `welcome`.
21
+ */
22
+ export declare const GROUP_LIMITS: {
23
+ /** Application text, UTF-8 bytes. */
24
+ readonly textBytes: number;
25
+ /** Own messages kept for catch-up: count and total ciphertext bytes. */
26
+ readonly outlog: 32;
27
+ readonly outlogBytes: number;
28
+ /** Frames waiting for an epoch (or its secret) that has not arrived yet. */
29
+ readonly waiting: 64;
30
+ readonly waitingBytes: number;
31
+ /** Epoch secrets kept: past this, older epochs cannot be read or handed on. */
32
+ readonly secrets: 32;
33
+ /** Secrets in one `group-secrets` frame: apps from before revision 0.9 drop a frame with more. */
34
+ readonly secretsPerFrame: 16;
35
+ /**
36
+ * Other members' messages kept to hand on to a member who missed them (any member catches up the others): count
37
+ * and total ciphertext bytes. The oldest go first.
38
+ */
39
+ readonly relay: 256;
40
+ readonly relayBytes: number;
41
+ /** Other members' edits kept to hand on, the latest per message (WISP 902 § Edits): count and ciphertext bytes. */
42
+ readonly relayEdits: 64;
43
+ readonly relayEditBytes: number;
44
+ /** Edits of one member handed on for one sync that asks for them: fewer than a receiver takes in a window. */
45
+ readonly handOnEdits: 16;
46
+ /** Sequence numbers below the highest seen that a sync names as missing, per sender and epoch. */
47
+ readonly miss: 32;
48
+ /** Per sender and epoch, the sequence numbers remembered below the highest seen. */
49
+ readonly window: 256;
50
+ /** Commits ahead of the chain kept while the gap is fetched. */
51
+ readonly pendingCommits: 16;
52
+ /** Commits carried in one welcome or chain frame, and their size: a frame stays well within the 60 KiB an edge carries. */
53
+ readonly chainPiece: 24;
54
+ readonly chainPieceBytes: number;
55
+ /**
56
+ * Syncs of one member answered in `syncWindowMs`: an edge opening, a question every ten seconds at most and a gossip
57
+ * turn a minute fit well within; a member asking more is not answered until the window has room.
58
+ */
59
+ readonly syncAnswers: 8;
60
+ readonly syncWindowMs: 60000;
61
+ /** Messages delivered from a copy that was not whole, remembered until a whole copy completes them. */
62
+ readonly provisional: 256;
63
+ /**
64
+ * Frames of one catch-up answer in a slice (`GroupSessionHooks.handled`), two slices at most not handled yet by the
65
+ * member's app: the next goes once it handled the one before the last. An app holds 64 frames waiting at most before
66
+ * 2026-10-07 (more ends the session), and a member back in a busy group was handed over a hundred at once.
67
+ */
68
+ readonly catchUpSlice: 16;
69
+ /** Between two slices, when the member's app cannot say it handled one (`handled` resolves `false`). */
70
+ readonly catchUpPauseMs: 500;
71
+ /** A received message is in the saved state within this long (`persistSoon`): a burst of them is one save, not one each. */
72
+ readonly saveWithinMs: 1000;
73
+ };
74
+ /** What every member should know about who can read what, in the words the apps show. */
75
+ export declare const GROUP_READ_NOTE: string;
76
+ /**
77
+ * `m`: the message's mentions (`GroupMention[]` as JSON), sealed under the same epoch key with a nonce of their own
78
+ * and bound to the header. Outside the signature, which older apps check as it was: only the author's edge ever
79
+ * carries its frame, so the edge vouches for it. Older apps ignore the field.
80
+ */
81
+ /**
82
+ * `xs`: the author's signature over the whole frame, the boxes of `m` and `r` included (revision 0.9), and `f` when
83
+ * there is one. A frame handed on by another member keeps its boxes only with it: the edge it arrives on is not the
84
+ * author's and vouches for nothing.
85
+ * `f`: a forwarded text's hop count (WISP 902 § Forwards), in the clear like the header: every member reads it anyway.
86
+ * `sc`: a status card (WISP 405 · Status Cards) as JSON, sealed like the reply in a box of its own, so an older app
87
+ * reads the text, its fallback; `xs` covers it after the rest, only when there is one.
88
+ * `fl`: a file or voice message the message announces (WISP 503 · Group Files), its description as JSON, sealed in a box
89
+ * of its own; the text is the caption, or a line an older app shows instead. `xs` covers it after `sc`, before `o`.
90
+ * `o`: where a message said again under a later epoch was first said (WISP 902 § Catch-up, "Frames said again"): that
91
+ * frame's epoch and sequence, in the clear like the header. `xs` covers it last, only when there is one.
92
+ */
93
+ export interface GroupMessageFrame {
94
+ t: "group-msg";
95
+ g: string;
96
+ e: number;
97
+ s: string;
98
+ n: number;
99
+ ts: number;
100
+ nn: string;
101
+ c: string;
102
+ sig: string;
103
+ m?: {
104
+ n: string;
105
+ c: string;
106
+ };
107
+ r?: {
108
+ n: string;
109
+ c: string;
110
+ };
111
+ f?: number;
112
+ sc?: {
113
+ n: string;
114
+ c: string;
115
+ };
116
+ fl?: {
117
+ n: string;
118
+ c: string;
119
+ };
120
+ o?: {
121
+ e: number;
122
+ n: number;
123
+ };
124
+ xs?: string;
125
+ }
126
+ /**
127
+ * An edit of message `<s>:<e>:<n>` by its author (WISP 902 § Edits): edit number `v`, the new text (and its mentions)
128
+ * as JSON `{ text, m?, sc? }` sealed under the key of the message's epoch `e`, signed by the author. `sc`: the status card
129
+ * of this version (WISP 405 · Status Cards); with one, `v` may go up to `STATUS_CARD_LIMITS.edits`.
130
+ */
131
+ export interface GroupEditFrame {
132
+ t: "group-edit";
133
+ g: string;
134
+ e: number;
135
+ s: string;
136
+ n: number;
137
+ v: number;
138
+ ts: number;
139
+ nn: string;
140
+ c: string;
141
+ sig: string;
142
+ }
143
+ export interface GroupCommitFrame {
144
+ t: "group-commit";
145
+ g: string;
146
+ commit: GroupCommit;
147
+ secret?: SealedSecret;
148
+ }
149
+ /**
150
+ * `mt`: which metadata statement I hold (`groupMetaTag`); apps without metadata leave it out. `miss`: sequence numbers
151
+ * below the highest in `have` that never arrived, per sender and epoch. `ask`: members whose messages I want the
152
+ * receiver to hand on (their edges to me are down); apps from before revision 0.9 send neither and are handed nothing.
153
+ */
154
+ export interface GroupSyncFrame {
155
+ t: "group-sync";
156
+ g: string;
157
+ e: number;
158
+ h: string;
159
+ have: Record<string, Record<string, number>>;
160
+ secrets: number[];
161
+ mt?: string;
162
+ miss?: Record<string, Record<string, number[]>>;
163
+ ask?: string[];
164
+ }
165
+ export interface GroupSecretsFrame {
166
+ t: "group-secrets";
167
+ g: string;
168
+ secrets: {
169
+ e: number;
170
+ s: SealedSecret;
171
+ }[];
172
+ }
173
+ export interface GroupLeaveFrame {
174
+ t: "group-leave";
175
+ g: string;
176
+ }
177
+ export interface GroupInviteFrame {
178
+ t: "group-invite";
179
+ g: string;
180
+ name: string;
181
+ admin: string;
182
+ e: number;
183
+ n: number;
184
+ }
185
+ export interface GroupAcceptFrame {
186
+ t: "group-accept";
187
+ g: string;
188
+ key: string;
189
+ }
190
+ export interface GroupDeclineFrame {
191
+ t: "group-decline";
192
+ g: string;
193
+ }
194
+ export interface GroupChainFrame {
195
+ t: "group-chain";
196
+ g: string;
197
+ commits: GroupCommit[];
198
+ }
199
+ export interface GroupWelcomeFrame {
200
+ t: "group-welcome";
201
+ g: string;
202
+ name: string;
203
+ commits: GroupCommit[];
204
+ secrets: {
205
+ e: number;
206
+ s: SealedSecret;
207
+ }[];
208
+ }
209
+ export interface GroupRemovedFrame {
210
+ t: "group-removed";
211
+ g: string;
212
+ }
213
+ /**
214
+ * A member's leave, signed by its member key (WISP 902 · Group Mesh § Hubs): unlike `group-leave`, which the admin
215
+ * believes from the edge it comes on, hubs can carry it to an admin the member has no edge with. Apps from before drop it.
216
+ */
217
+ export interface GroupByeFrame {
218
+ t: "group-bye";
219
+ g: string;
220
+ k: string;
221
+ e: number;
222
+ ts: number;
223
+ sig: string;
224
+ }
225
+ export type GroupEdgeFrame = GroupMessageFrame | GroupEditFrame | GroupCommitFrame | GroupSyncFrame | GroupSecretsFrame | GroupLeaveFrame | GroupMetaFrame | GroupByeFrame;
226
+ export type GroupAdmissionFrame = GroupInviteFrame | GroupAcceptFrame | GroupDeclineFrame | GroupChainFrame | GroupWelcomeFrame | GroupRemovedFrame;
227
+ export type GroupStatus = "active" | "left" | "removed" | "forked";
228
+ export interface GroupState {
229
+ id: string;
230
+ name: string;
231
+ profile: typeof GROUP_PROFILE;
232
+ /** My member key seed for this group and nothing else. Wiped once I am out. */
233
+ seedB64: string;
234
+ createdAt: number;
235
+ chain: GroupCommit[];
236
+ /** Epoch → secret (base64url); only the epochs I was a member of, at most `secrets` of them. */
237
+ secrets: Record<string, string>;
238
+ status: GroupStatus;
239
+ statusReason?: string;
240
+ /** My next sequence number, in `seqEpoch`. */
241
+ seq: number;
242
+ seqEpoch: number;
243
+ /** My own frames, newest last, for members who missed them. */
244
+ sent: GroupMessageFrame[];
245
+ /** Other members' frames, in the order they arrived, for members who missed them. Absent in states from before revision 0.9. */
246
+ relay?: GroupMessageFrame[];
247
+ /** Other members' edits, the latest per message, for members who missed them. Absent in states from before edits were handed on. */
248
+ relayEdits?: GroupEditFrame[];
249
+ /** Sender → epoch → highest sequence seen and the ones seen below it. */
250
+ seen: Record<string, Record<string, {
251
+ high: number;
252
+ window: number[];
253
+ }>>;
254
+ /**
255
+ * Messages delivered from a copy that was not whole, waiting for a whole copy to complete them, oldest first, at most
256
+ * `GROUP_LIMITS.provisional`. Absent in states from before they were saved.
257
+ */
258
+ provisional?: string[];
259
+ /** Names members announced on their edges. */
260
+ nicks: Record<string, string>;
261
+ /** The group's metadata (its picture), as the admin last signed it and I accepted it. */
262
+ meta?: GroupMeta;
263
+ /**
264
+ * My frames no edge took when I said them, as `e:n`, oldest first, kept until each was looked at once for saying again
265
+ * (`resealBehind`): I may have been behind on the chain without knowing. Absent in older states.
266
+ */
267
+ alone?: string[];
268
+ }
269
+ /**
270
+ * `completes`: this message was delivered before from a copy another member handed on without its author's whole
271
+ * signature (its text only); this is the whole one, with the mentions, reply and hop count its author put there.
272
+ */
273
+ /**
274
+ * `frame`: the frame the message came in, as it is kept to hand on to a member who missed it (only its author's own
275
+ * fields, signed by its author); only with a whole copy. An app keeps it with the message it stores.
276
+ */
277
+ export interface GroupIncomingMessage {
278
+ id: string;
279
+ sender: string;
280
+ epoch: number;
281
+ seq: number;
282
+ timestamp: number;
283
+ text: string;
284
+ mentions?: GroupMention[];
285
+ reply?: WireReply;
286
+ forwarded?: number;
287
+ card?: StatusCard;
288
+ file?: GroupFileMeta;
289
+ completes?: true;
290
+ frame?: GroupMessageFrame;
291
+ }
292
+ export interface GroupSessionHooks {
293
+ save(state: GroupState): Promise<void>;
294
+ /** Best effort, over the pairwise edge to that member if it is open: whether it went, when the host says. */
295
+ send(to: string, frame: GroupEdgeFrame): boolean | void;
296
+ /** Store before it resolves: replay state advances only afterwards. */
297
+ message(message: GroupIncomingMessage): Promise<void> | void;
298
+ /** An edit of a member's message, authenticated as its author (WISP 902 § Edits). Apps without edits leave it out. */
299
+ edit?(edit: GroupIncomingEdit): Promise<void> | void;
300
+ /** Roster, epoch or status changed. */
301
+ changed(): void;
302
+ /**
303
+ * The group's name or picture changed (set, replaced or removed), by `by`, in a statement signed at `at`. `by` is
304
+ * undefined when the signer may only have signed again what an admin before them set (`metaAuthor`).
305
+ */
306
+ metaChanged?(by: string | undefined, change: GroupMetaChange, at: number): void;
307
+ /** The clock the limits read (the engine's, or a simulation's); the wall clock when absent. */
308
+ clock?(): number;
309
+ /**
310
+ * The lowest sequence number this member sends at, in any epoch (WISP 06 § Raised counters): 0 for a profile that
311
+ * never took over or was never restored. A copy of a profile started from older state sends above every number the
312
+ * copy it replaced may have used, so the other members do not drop its frames as already seen.
313
+ */
314
+ seqFloor?(): number;
315
+ /**
316
+ * Resolves once the member's app handled every frame sent to it so far (it answers a ping in the order frames come),
317
+ * or `false` when it cannot tell (no session, or an app that answers no ping): a catch-up answer then waits
318
+ * `GROUP_LIMITS.catchUpPauseMs` between slices; `"late"` when it answers pings but has not handled them yet, and the
319
+ * answer asks again. Absent: an answer goes all at once, as before 2026-10-07.
320
+ */
321
+ handled?(to: string): Promise<CatchUpHandled>;
322
+ /**
323
+ * Whether this device may sign commits for the group (WISP 06 § Forced takeover): false after a forced takeover or a
324
+ * restore, until the person turns on "Manage groups from this device" there. Then no commit is signed, the automatic
325
+ * one on a member's leave included: the copy may lack the last commit the device it replaced made, and two commits
326
+ * after one parent halt the group. Absent: true.
327
+ */
328
+ adminWork?(): boolean;
329
+ /**
330
+ * Whether a fresh turn read says this device is the active one (WISP 06 § When a device checks), asked before every
331
+ * commit: two devices that both think they are active would each commit after one parent, and the group halts. No:
332
+ * a commit the person asked for is refused (`groupTurnUnconfirmed`); an automatic one (a member's leave) is not made
333
+ * here, and the leave is passed on as a member passes it. Absent: yes.
334
+ */
335
+ adminTurn?(): Promise<boolean>;
336
+ }
337
+ export declare const groupMessageId: (sender: string, epoch: number, seq: number) => string;
338
+ /**
339
+ * A member's reaction as a hub passes it on: signed by the member (`k`), unlike `group-react`, which the edge it comes
340
+ * on vouches for. A frame of its own, which apps from before hubs drop: they would take it as the hub's reaction.
341
+ */
342
+ export declare const GROUP_REACTED_FRAME = "group-reacted";
343
+ export interface GroupReactedFrame extends WireReaction {
344
+ t: typeof GROUP_REACTED_FRAME;
345
+ g: string;
346
+ k: string;
347
+ sig: string;
348
+ }
349
+ export interface GroupPinFrame extends WirePin {
350
+ t: typeof GROUP_PIN_FRAME;
351
+ g: string;
352
+ k: string;
353
+ sig: string;
354
+ }
355
+ /** What a frame weighs in a log, roughly: its boxes plus the fixed fields around them. */
356
+ /** What a kept frame counts for against `GROUP_LIMITS.relayBytes`. */
357
+ export declare const frameBytes: (f: GroupMessageFrame) => number;
358
+ /**
359
+ * My own messages and the ones I kept of other members, as one list for a member catching up: each log keeps its own
360
+ * order (mine as I sent them, the others' as they reached me, which no member's clock can change), and the two are
361
+ * merged by the time each frame says, mine first when they say the same. A member whose clock is off moves only
362
+ * where its lines fall among mine, never the order within a log.
363
+ */
364
+ export declare function asWritten(own: readonly GroupMessageFrame[], kept: readonly GroupMessageFrame[]): GroupMessageFrame[];
365
+ /** The chain cut in consecutive pieces of at most `chainPiece` commits and `chainPieceBytes`: a roster of 32 makes a commit ~2.4 KB. */
366
+ export declare function chainPieces(chain: GroupCommit[]): GroupCommit[][];
367
+ export declare class GroupSession {
368
+ private readonly hooks;
369
+ readonly state: GroupState;
370
+ private readonly identity;
371
+ /** Frames for an epoch, or a secret, not here yet. In memory only. */
372
+ private waiting;
373
+ private waitingBytes;
374
+ /** Edits for an epoch, or a secret, not here yet: tried again with the frames above. In memory only. */
375
+ private waitingEdits;
376
+ private pendingCommits;
377
+ /** When each member was last asked to catch me up, so a stream of unreadable frames is one question, not a loop. */
378
+ private asked;
379
+ /** The signed leave of each member I last passed on, kept for an admin that was away (`byesHeld`). In memory only. */
380
+ private byesPassed;
381
+ private queue;
382
+ /** One metadata frame that names a commit or an epoch I do not have yet: tried again when the chain moves. */
383
+ private pendingMeta;
384
+ /** While `handle` runs: the frames it took that a hub passes on (`handle`'s result). */
385
+ private passOn;
386
+ /** Set while a save of what received messages changed is due (`persistSoon`). */
387
+ private saveTimer;
388
+ /** Syncs answered per member, a few a minute (`GROUP_LIMITS.syncAnswers`). In memory only. */
389
+ private syncsAnswered;
390
+ /** Catch-up answers still going out, a slice at a time (`handOut`). */
391
+ private readonly answers;
392
+ /**
393
+ * Messages delivered from a copy that was not whole (handed on without its author's whole signature): not seen, so
394
+ * a sync still asks for them and a whole copy completes them. Oldest first, saved as `GroupState.provisional`, so a
395
+ * restart does not let a stripped copy take the message's place.
396
+ */
397
+ private provisional;
398
+ /** When my chain last moved (a commit made or applied), by `hooks.clock`: frames are said again once it has settled. */
399
+ private chainMovedAt;
400
+ constructor(state: GroupState, hooks: GroupSessionHooks);
401
+ private clock;
402
+ /** A new group: its genesis commit, signed by the creator, who is its admin. */
403
+ static create(name: string, now?: number): GroupState;
404
+ /**
405
+ * Joining from a welcome: the chain must verify from its genesis, admit me
406
+ * in a commit signed by the admin the invitation named (learned over the
407
+ * inviter's authenticated contact link), end with me in the roster, and
408
+ * come with the secret of the current epoch, confirmed against its commit.
409
+ * Earlier epochs I was a member of may come too; nothing before my admission can.
410
+ */
411
+ static join(invite: {
412
+ name: string;
413
+ admin: string;
414
+ }, pieces: unknown[], welcome: unknown, seedB64: string, now?: number): {
415
+ state: GroupState;
416
+ } | {
417
+ error: string;
418
+ };
419
+ get id(): string;
420
+ /** The name the admin gave the group, else the one it had when I got in (WISP 902 § Metadata). */
421
+ get name(): string;
422
+ get myKey(): string;
423
+ get epoch(): number;
424
+ get top(): GroupCommit;
425
+ get roster(): Roster;
426
+ get admin(): string | undefined;
427
+ get isAdmin(): boolean;
428
+ get status(): GroupStatus;
429
+ /** Members other than me, in the current roster. */
430
+ get others(): string[];
431
+ /**
432
+ * Whether `key` could read message `messageId` (`<s>:<e>:<n>`) and still can: in the roster of its epoch, and in the
433
+ * roster now. A holder serves a group file only to such a member (WISP 503 § Asking).
434
+ */
435
+ couldRead(key: string, messageId: string): boolean;
436
+ role(key: string): GroupRole | undefined;
437
+ /** The group's picture, if it has one. */
438
+ get picture(): string | undefined;
439
+ /** Whom the admin pinned as hubs and excluded (WISP 902 · Group Mesh § Hubs), from the group's metadata. */
440
+ get hubPolicy(): MeshHubPolicy;
441
+ private policyOf;
442
+ /** The current epoch's rendezvous secret (its beacon and lobbies), once its secret is here. */
443
+ get rendezvous(): string | undefined;
444
+ /** Epochs whose messages this member can still read. */
445
+ get readableEpochs(): number[];
446
+ /**
447
+ * A frame signed with my own key that I did not send here: another copy of this profile sent it (a restored backup, a
448
+ * device that took over while this one was away, WISP 06). It is not shown, as before; but my counter goes above it
449
+ * in this epoch, so what I send next is not dropped by the others as already seen.
450
+ */
451
+ private ownFrame;
452
+ /** `GroupSessionHooks.seqFloor`, as a whole number that is never negative. */
453
+ private seqFloor;
454
+ /**
455
+ * How many messages, per sender, are known to be missing in the current epoch. `past`: only the numbers above it,
456
+ * for a caller that knows nobody holds the ones up to it any more.
457
+ */
458
+ missing(sender: string, past?: number): number;
459
+ /**
460
+ * The other members some of whose messages below the highest seen never arrived (what a sync names in `miss`), each
461
+ * with a mark that changes when what is missing does: an author answers only from its own last `outlog`, so the rest
462
+ * is for another member to hand on.
463
+ */
464
+ lacking(): Map<string, string>;
465
+ /** What a sync names in `miss` for one sender now: per epoch, the newest `GROUP_LIMITS.miss` numbers that never arrived. */
466
+ missOf(sender: string): Record<string, number[]>;
467
+ /** Whether any of `asked` (per epoch, as `missOf` gave them) arrived since: the member asked holds what is missing. */
468
+ filledSince(sender: string, asked: Record<string, number[]>): boolean;
469
+ private serialize;
470
+ private persist;
471
+ /**
472
+ * A save within `GROUP_LIMITS.saveWithinMs`, for what a received message changes (what was seen, what is kept to hand
473
+ * on): the state holds the whole hand-on log, and a member back in a busy group wrote all of it once per message.
474
+ * The message itself is stored before (`hooks.message`). An app killed before the save takes those frames again when
475
+ * it syncs: its store has the messages already, and the state then catches up.
476
+ */
477
+ private persistSoon;
478
+ /** Writes what is waiting to be saved now (before a restart, in tests). */
479
+ flush(): Promise<void>;
480
+ private secret;
481
+ private requireAdmin;
482
+ /** What the admin sends a contact over their chat to invite them. */
483
+ inviteFrame(): GroupInviteFrame;
484
+ /**
485
+ * Admits a member who accepted: a new epoch whose secret goes to everyone in
486
+ * the new roster. Returns the welcome for the newcomer (to send over the
487
+ * contact link) after telling the existing members over their edges.
488
+ */
489
+ admit(memberKey: string, now?: number): Promise<(GroupChainFrame | GroupWelcomeFrame)[]>;
490
+ remove(memberKey: string, now?: number): Promise<void>;
491
+ transferAdmin(memberKey: string, now?: number): Promise<void>;
492
+ /** A fresh secret without a membership change: whoever holds the old one and is not a member learns nothing new. */
493
+ rotate(now?: number): Promise<void>;
494
+ private commit;
495
+ /** Someone out of the roster is not handed on any more, whatever they sent while in it (WISP 902 § Catch-up). */
496
+ private pruneRelay;
497
+ /** Another member's edit, kept to hand on: the latest per message; the oldest go once the log is full. False: one as new was kept. */
498
+ private keepEdit;
499
+ /** A frame of another member, kept to hand on; the oldest go once the log is full. */
500
+ private keep;
501
+ private pruneSecrets;
502
+ /** Leaves: my secrets go now; the admin removes me from the roster when it hears. */
503
+ leave(): Promise<void>;
504
+ /** Told out of band (the admin's contact chat) that I was removed, before or instead of the commit. */
505
+ markRemoved(): Promise<void>;
506
+ private out;
507
+ /**
508
+ * Encrypts and signs a text, keeps it for catch-up and sends it to every other member. `mentions`: places of the
509
+ * text that name members (everyone: the admin only); what does not hold is left out. `reply`: the message it
510
+ * answers, sealed apart from the text (`r`) like the mentions, so an older app still reads the text. `forwarded`: the
511
+ * hop count of a forwarded text (`f`, WISP 902 § Forwards). `card`: a status card, checked by the caller, sealed in a
512
+ * box of its own (`sc`, WISP 405 · Status Cards); the text is its fallback. `file`: a file or voice message the text
513
+ * announces (`fl`, WISP 503 · Group Files), its description checked by the caller; the text is its caption, or the
514
+ * line an older app shows.
515
+ */
516
+ sendText(text: string, now?: number, mentions?: readonly GroupMention[], reply?: WireReply, forwarded?: number, card?: StatusCard, file?: GroupFileMeta): Promise<{
517
+ id: string;
518
+ } | {
519
+ error: string;
520
+ }>;
521
+ /** My next sequence number in `epoch`: the running counter in the current one, past every frame of mine I keep in an older one. */
522
+ private nextSeq;
523
+ /** A text sealed and signed as my frame `n` of `epoch`, with its boxes; `o`: where it was first said (`resealBehind`). */
524
+ private seal;
525
+ /** Into my bounded log, for members who missed it. */
526
+ private logOwn;
527
+ /**
528
+ * Saves, then sends my frame to every other member of its epoch still in the group. One no edge took (none was up:
529
+ * my app just opened) is remembered (`alone`): I may be behind on the chain without knowing, and members let in
530
+ * meanwhile could never open it (`resealBehind`).
531
+ */
532
+ private say;
533
+ /**
534
+ * My frames sealed under an epoch I took for the newest while I was behind (no edge was up, and others were let in
535
+ * meanwhile): the members let in before I said them could never open them. Once my chain is newer than such a
536
+ * frame's, has not moved for `SAID_AGAIN.settledMs` and nothing is missing, each is looked at once: when a member in
537
+ * the roster now, not in the frame's epoch, was let in by an `add` dated no later than the frame, the same text (and
538
+ * boxes, and time) is sealed again with `o` naming the first, under the newest epoch before any `add` dated after the
539
+ * frame. So it reaches those let in before it, never one let in after, and everyone keeps one id for it (replies,
540
+ * edits, reactions); one who read the first does not show it twice. The engine calls this on each tick.
541
+ */
542
+ reseal(): Promise<void>;
543
+ /** Something is missing here: the current epoch's secret, a commit ahead of my chain, or the epoch of frames waiting. */
544
+ private get behind();
545
+ private resealBehind;
546
+ /**
547
+ * The epoch my frame `f` is said again under, or none: the newest after its own, before any `add` dated later than
548
+ * the frame (by the admitting member's clock against mine), when its roster holds a member still in the group that
549
+ * the frame's epoch did not. Its readers were all let in no later than the frame.
550
+ */
551
+ private saidAgainEpoch;
552
+ /**
553
+ * The message one of my frames (or edits) is: the first frame's id for a frame said again (`o`), else its own. An
554
+ * edit of a copy said again names the copy; its id is the first's too.
555
+ */
556
+ messageIdOf(f: {
557
+ s: string;
558
+ e: number;
559
+ n: number;
560
+ o?: unknown;
561
+ }): string;
562
+ /**
563
+ * Says an edit of one of my messages (WISP 902 § Edits): edit `v`, the whole new text and its mentions, sealed under
564
+ * the key of the message's epoch and signed, to every member of that epoch still in the group, or to `to` alone (an
565
+ * edge that just opened). Someone admitted after the message cannot open it and is not sent it. The message's
566
+ * epoch key must still be here: past `GROUP_LIMITS.secrets` epochs a message cannot be edited.
567
+ */
568
+ sendEdit(messageId: string, edit: {
569
+ v: number;
570
+ ts: number;
571
+ text: string;
572
+ mentions?: readonly GroupMention[];
573
+ card?: StatusCard;
574
+ }, to?: string): Promise<{
575
+ sent: number;
576
+ } | {
577
+ error: string;
578
+ }>;
579
+ /**
580
+ * What to tell a member whose edge just opened: where I am, what I have from everyone and what never arrived below
581
+ * that. `ask`: the members whose messages I want this one to hand on, since their own edges to me are down.
582
+ */
583
+ syncFrame(ask?: readonly string[]): GroupSyncFrame;
584
+ /** Sequence numbers below the highest seen that never arrived, the newest `miss` of them. */
585
+ private gaps;
586
+ setNick(key: string, nick: string | undefined): Promise<void>;
587
+ /**
588
+ * A frame from an authenticated member over the pairwise edge. Anything malformed or unauthorized is dropped.
589
+ * Resolves to what it took that a hub passes on to its other edges (WISP 902 · Group Mesh § Hubs): each message,
590
+ * edit, commit (without the secret sealed for me), metadata statement and signed leave, the first time only, so a
591
+ * flood among hubs stops at every member that already has it. Only what its author still in the roster signed.
592
+ */
593
+ handle(from: string, raw: unknown): Promise<GroupEdgeFrame[]>;
594
+ /** Taken for the first time: a hub passes it on (see `handle`). */
595
+ private took;
596
+ /**
597
+ * My leave, signed, for hubs to carry to the admin (see `GroupByeFrame`). Made while I am still a member: `leave`
598
+ * forgets everything but my key.
599
+ */
600
+ byeFrame(now?: number): GroupByeFrame;
601
+ /** My signature on a reaction of mine, beside its wire fields (older apps read only those). */
602
+ signReaction(reaction: WireReaction): {
603
+ k: string;
604
+ sig: string;
605
+ };
606
+ /**
607
+ * A reaction signed by a member still in the roster (not me), with the member and the reaction, or null: what a hub
608
+ * passes on, and what a member takes from a hub.
609
+ */
610
+ signedReaction(raw: unknown): {
611
+ member: string;
612
+ reaction: WireReaction;
613
+ frame: GroupReactedFrame;
614
+ } | null;
615
+ /** My pin, signed, as it goes over every edge. */
616
+ pinFrame(pin: WirePin): GroupPinFrame;
617
+ /** A pin signed by a member still in the roster (me too: it may come back through another member), or null. */
618
+ signedPin(raw: unknown): {
619
+ member: string;
620
+ pin: WirePin;
621
+ frame: GroupPinFrame;
622
+ } | null;
623
+ /** A signed leave: the admin removes its member; anyone else passes it on while that member is in the roster. */
624
+ private receiveBye;
625
+ /**
626
+ * The signed leaves I passed on whose members are still in the roster: the admin was away when they went round, so
627
+ * they are handed to it again when its edge opens. One goes with the commit that removes its member.
628
+ */
629
+ byesHeld(): GroupByeFrame[];
630
+ /** The epoch of the commit that last admitted `key` (0 for the creator, whom no commit admits). */
631
+ private admittedAt;
632
+ /**
633
+ * An automatic commit (a member's leave): made, or not made when no fresh turn read says this device is the active
634
+ * one (`adminTurn`). Then false, and the caller goes on as a member would. Any other refusal is thrown as before.
635
+ */
636
+ private commitUnlessTurnUnconfirmed;
637
+ /**
638
+ * A message, from its author's edge or handed on by another member. Handed on, it is taken only while both are in
639
+ * the roster (someone removed is neither heard from nor handed on, #300), and its boxes only with the author's `xs`.
640
+ */
641
+ private receiveMessage;
642
+ /**
643
+ * An edit of a member's own message, from its author's edge or handed on by another member: believed only while its
644
+ * author is still in the roster (someone removed edits nothing), and the member handing it on too; for an epoch the
645
+ * author and I were both members of, with the author's signature over the whole frame and a box that opens. One for
646
+ * an epoch or a secret not here yet waits, as a message does. Taken, it is kept to hand on in turn.
647
+ */
648
+ private receiveEdit;
649
+ private parkEdit;
650
+ private wholeSigned;
651
+ private openMentions;
652
+ /** A message's status card; a box that does not open, or a card that does not hold, is no card: the text shows. */
653
+ private openCard;
654
+ /** The file a message announces (WISP 503); a box that does not open, or a description that does not hold, is no file. */
655
+ private openFile;
656
+ /** The message a text answers; a box that does not open, or does not hold one, is no reply, not no message. */
657
+ private openReply;
658
+ private isDuplicate;
659
+ private markSeen;
660
+ private park;
661
+ /** Whoever sent something I cannot read yet is ahead of me, or holds a secret I lack: ask, but not in a loop. */
662
+ private ask;
663
+ private replayWaiting;
664
+ private receiveCommit;
665
+ private apply;
666
+ /** A sealed secret for an epoch of my chain: kept only when it confirms against that epoch's commit. */
667
+ private takeSecret;
668
+ private receiveSecrets;
669
+ private receiveSync;
670
+ /**
671
+ * A catch-up answer, a slice at a time (`GROUP_LIMITS.catchUpSlice`), with two slices at most not handled yet by the
672
+ * member's app (`hooks.handled`), as a community's goes (`CatchUpAnswers`). All at once, a member back in a busy group
673
+ * was handed over a hundred frames on one session, and an app that holds 64 waiting ended that session mid catch-up
674
+ * ("Session receive limit exceeded", 2026-10-07). A newer answer to the same member takes the place of what is left of
675
+ * the last; a frame the edge did not take ends it (the member asks again when its edge opens).
676
+ */
677
+ private handOut;
678
+ /** My own messages a member's sync says it lacks, from my bounded log, for the epochs it was a member of. */
679
+ private handOwn;
680
+ private ownLacked;
681
+ /** Sets (or, with null, removes) the group's picture: only the admin, signed under the current commit. */
682
+ setPicture(picture: string | null, now?: number): Promise<void>;
683
+ /** Renames the group: only the admin, signed under the current commit, beside the picture and the hubs. */
684
+ rename(name: string, now?: number): Promise<void>;
685
+ /**
686
+ * Pins a member as a hub, excludes one from being a hub, or leaves it to the member's app (`null`): only the admin,
687
+ * in the group's metadata beside the picture (WISP 902 · Group Mesh § Hubs).
688
+ */
689
+ setHub(key: string, role: "pin" | "exclude" | null, now?: number): Promise<void>;
690
+ /** Signs a body under my current commit, keeps it and sends it to every member. Inside `serialize`. */
691
+ private publishMeta;
692
+ /** My statement, to a member whose sync says it holds an older one (or none); nothing to an app that says nothing. */
693
+ private offerMeta;
694
+ private metaFor;
695
+ /**
696
+ * A metadata statement: kept when it is newer than mine, its commit is on my chain, its signer was
697
+ * the admin of that commit and is the admin now, its signature holds, and it opens under the epoch
698
+ * it names into metadata Ghostly shows. One naming what I do not have yet waits for the chain.
699
+ */
700
+ private receiveMeta;
701
+ /**
702
+ * Who made the change a statement brings me: its signer, when they were the admin all along since the statement I
703
+ * held (or, with none, since I got in). A new admin signs again what the last one set (`metaFollowsChain`): to a
704
+ * member that missed that, it is no change of theirs it can tell apart, so nobody is named.
705
+ */
706
+ private metaAuthor;
707
+ /** After the chain or my secrets moved: the waiting statement, and, if I became the admin, the name and picture signed again as mine. */
708
+ private metaFollowsChain;
709
+ private fork;
710
+ }