@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,1510 @@
1
+ import { type DeliveryMode, type DhtDeliveryState, type DhtDeliveryView, type DhtPacketFacts } from "./dhtDelivery.js";
2
+ import type { DhtFileAnnouncement, DhtFileOffer } from "./dhtFiles.js";
3
+ import { type ProofAdapter, type ProofScope } from "./peerProofs.js";
4
+ import { type IdentityScope } from "./identityProofs.js";
5
+ import { type NativeEndpoint, type PairedTransport, type TransportDescriptors } from "./pairedTransports.js";
6
+ import { type LinkPreview } from "./linkPreview.js";
7
+ import { type WireReply } from "./replies.js";
8
+ import { type StatusCard } from "./statusCards.js";
9
+ import { type DeviceCapability, type DeviceFrame } from "./deviceLink.js";
10
+ import { type PairingState, type PairingCredentials, type PaymentMethodName } from "./pairedSession.js";
11
+ import { DataLink, type DataLinkState } from "./datalink.js";
12
+ import type { DirectEvidence } from "./directPath.js";
13
+ import { type FileInfo, type FileSink } from "./files.js";
14
+ import { type ClientRequest, type ClientResponse, type HostedHttpService, type LocalFetch } from "./http.js";
15
+ import type { LinkParams } from "./invite.js";
16
+ import type { Payment, PaymentAsk, PaymentRequest, PaymentResult } from "./payments.js";
17
+ import { LinkSession, type LinkStatus, type PeerPresence, type PollIntervals } from "./link.js";
18
+ import type { ResolvedLink } from "./records.js";
19
+ import { type ServiceAd } from "./services.js";
20
+ import { type SessionCapability } from "./pairedCapabilities.js";
21
+ import { type AppFrameEvent, type AppSendError } from "./pairedApps.js";
22
+ import { type WakeTarget } from "./pairedWake.js";
23
+ import { type WireReaction } from "./reactions.js";
24
+ import { type WirePin } from "./pins.js";
25
+ import { type TypingActivity } from "./pairedTyping.js";
26
+ import { type WireEdit } from "./pairedEdits.js";
27
+ import { type PkarrTransport } from "./transport.js";
28
+ import { type PairingProgress, type PairingRole } from "./pairingProgress.js";
29
+ /** A native transport that fails this many attempts in a row is skipped for `DEMOTE_MS`, while another remains (WISP 100). */
30
+ /** Pinned over the DHT with no stream up this long after, a first pairing shows as on the DHT (WISP 400). */
31
+ export declare const DHT_PIN_GRACE_MS = 10000;
32
+ /** Back after a restart (`resume`), dials wait this long at most for the native endpoint that carried the chat to start. */
33
+ export declare const RESUME_WAIT_MS = 10000;
34
+ /** Two dials crossing: how long the lower key's side waits for its own to connect before it takes the contact's. */
35
+ export declare const CROSSED_WAIT_MS = 3000;
36
+ /**
37
+ * A session this side dialled this recently is one a crossing dial of the contact's may meet (both connected): the
38
+ * lower key keeps its own. Older, the session is one the contact has since lost (its app restarted), and its dial
39
+ * takes over.
40
+ */
41
+ export declare const CROSSED_FRESH_MS = 10000;
42
+ /** A joiner gathers its offer while it first looks for the inviter (`dialEarly`) only this soon after the join. */
43
+ export declare const EARLY_DIAL_JOIN_MS = 60000;
44
+ /** What a joiner is told when someone else used the invite first (`DhtDeliveryView.inviteTaken`). */
45
+ export declare const INVITE_TAKEN = "Someone else joined with this invite first. Ask your contact for a new one.";
46
+ /**
47
+ * A dial the contact made while its mailbox, as last read here, said DHT-only waits this long for the read that says
48
+ * it left (the mailbox is read at the DHT pace meanwhile), then closes.
49
+ */
50
+ export declare const BLOCKED_DIAL_WAIT_MS = 10000;
51
+ /**
52
+ * A connection dialled in on a pinned chat must authenticate within this long, or it closes. Anyone who read the
53
+ * endpoint from the record can dial it: until it proves the pinned key it holds no place a person waits on. A native
54
+ * connection this side dialled on a pinned chat has as long too: its path is up when it opens, and the handshake takes
55
+ * a few round trips, so one still unfinished by then carries nothing (a relay path that died with the handshake), and
56
+ * the chat dials again rather than hold it until QUIC's idle timeout (Omarchy, 2026-10-01: the web app had refused the
57
+ * Desktop's knock 15 s in, and the Desktop dialled again only 30 s in).
58
+ */
59
+ export declare const UNPROVEN_AUTH_MS = 15000;
60
+ /**
61
+ * A native connection this side dialled that has not authenticated this long after it opened, while the contact's
62
+ * record names a newer way to dial it: the dial went to an old address (the web app's Iroh homed on another relay after
63
+ * a restart), and the chat dials the new one at once. Sooner, it is a handshake still under way.
64
+ */
65
+ export declare const REDESCRIBED_GRACE_MS = 3000;
66
+ /**
67
+ * A WebRTC offer this side made that has no answer after this long: a direct native transport ranked after WebRTC is
68
+ * dialled meanwhile, the offer still standing, and whichever goes live first carries the chat. The contact may not read
69
+ * the offer for a while (a live chat reads every minute), or the relays' request budget may hold its answer back until
70
+ * its answering attempt is over, and the offer would wait out its attempt timeout (`CONNECT_TIMEOUT_MS`, 90 s). A native
71
+ * dial takes a second and no request to the relays.
72
+ */
73
+ export declare const RACE_DIRECT_MS = 8000;
74
+ /**
75
+ * A relayed one waits until a contact reading in the background (every 30 s) has had its look: a chat that went live
76
+ * over a relay stays there (no probing while live, WISP 100), where the answer would have made it direct.
77
+ */
78
+ export declare const RACE_RELAYED_MS = 40000;
79
+ /**
80
+ * A WebRTC offer this side made that was answered, and has not connected this long after the answer was applied: where
81
+ * a path exists ICE finds it in a second or two, so there is none (a VPN's NAT, a firewall that drops UDP, and no TURN
82
+ * server), and every transport ranked after WebRTC is dialled now, the relayed ones too, the attempt still standing.
83
+ * Without it the chat waited for ICE to give up (about 15 s in Chromium, the attempt's 90 s where the connection never
84
+ * says `failed`), then for the next attempt.
85
+ */
86
+ export declare const RACE_ANSWERED_MS = 6000;
87
+ /**
88
+ * WebRTC that could not start an attempt at all (no candidate gathered: UDP blocked, a VPN's browser extension; or no
89
+ * connection could be made) is tried last for this long: each try costs its stall time (`GATHER_STALL_MS` three times
90
+ * over) before the transport that works is dialled.
91
+ */
92
+ export declare const RTC_UNSTARTED_MS: number;
93
+ export declare const DEMOTE_AFTER_FAILURES = 3;
94
+ export declare const DEMOTE_MS: number;
95
+ /**
96
+ * WebRTC here refused more answers to this side's offers in a row than the data link offers again at once for
97
+ * (`ANSWER_REFUSED_REDIALS`): libdatachannel's race, which on a loaded core can refuse a whole run of them. The contact
98
+ * was there each time, so the next offer goes after a short pause, doubled each time, up to this many pauses, rather
99
+ * than after the backoff of failed dials (three minutes after five): a member let in to a group over slow relays was
100
+ * up with another member only 34 s after its welcome, and 180 s when that late dial was refused too (meshSignals on
101
+ * CI, 2026-10-11). Past them, the backoff as before: an answer that never goes in must not become a stream of offers.
102
+ */
103
+ export declare const ANSWERS_REFUSED_PAUSES = 3;
104
+ export declare const ANSWERS_REFUSED_PAUSE_MS = 2000;
105
+ /**
106
+ * A first pairing is different: the contact is right there, having just read the invite, so an attempt
107
+ * that did not make it in `PAIRING_ATTEMPT_MS` is given up and the next one starts after `PAIRING_RETRY_MS`
108
+ * (doubling up to `PAIRING_MAX_RETRY_MS`), instead of the 90 s and 20 s a saved contact's reconnect waits.
109
+ */
110
+ export declare const PAIRING_ATTEMPT_MS = 15000;
111
+ export declare const PAIRING_RETRY_MS = 3000;
112
+ /** An inviter that sees the joiner without its offer waits this long for one before offering itself. */
113
+ export declare const INVITER_DIAL_GRACE_MS = 2500;
114
+ /**
115
+ * Liveness of a paired session: a ping this often, and the session is taken for dead after this many
116
+ * pings in a row with nothing at all back. Counted in pings, not seconds, so a throttled background
117
+ * tab (timers once a minute) is not mistaken for a dead peer. Only once the peer has answered a ping:
118
+ * older apps drop the frame and must not be cut off for it.
119
+ */
120
+ export declare const LIVENESS_PING_MS = 15000;
121
+ /**
122
+ * After a live switch the old channel stays open this long, unread, before it is closed: the contact swaps on its own
123
+ * side a round trip later, and seeing its current channel close first would make it drop the whole session.
124
+ */
125
+ export declare const SWITCH_RETIRE_MS = 3000;
126
+ export declare const LIVENESS_MISSED_PINGS = 3;
127
+ /**
128
+ * A ping with nothing at all back this long after it went: the contact may have crashed and started again, with its new
129
+ * offer waiting on the relays, while this side still holds the old session and reads them at a live chat's pace (30 s).
130
+ * They are read now. Nothing more: the session is let go only by `LIVENESS_MISSED_PINGS`, or by the contact's offer
131
+ * (`DataLink.handleSignal`). A connection whose close this side does not hear (node-datachannel never says
132
+ * `disconnected`) otherwise went on until its consent checks gave up, 27 s after the crash (CI run 36741701666).
133
+ */
134
+ export declare const PONG_WAIT_MS = 4000;
135
+ /** How long `handled` waits for the contact to answer its ping before it says it is late. */
136
+ export declare const HANDLED_WAIT_MS = 10000;
137
+ /**
138
+ * Back in front after an absence (`wake`), a live session that ends this soon after it was lost while the app was
139
+ * away (a phone that put it to sleep): the chat resumes as after a restart, not as a session the contact closed.
140
+ */
141
+ export declare const WAKE_LOST_MS = 10000;
142
+ export interface IncomingMessage {
143
+ id?: string;
144
+ text: string;
145
+ timestamp: number;
146
+ nick?: string;
147
+ via: "pkarr" | "datalink";
148
+ batch?: ResolvedLink;
149
+ /** A paired chat's text from the DHT floor: the envelope it came in (`DhtPacketFacts`). */
150
+ packet?: DhtPacketFacts;
151
+ /** The link preview the sender's app attached (`pv`, WISP 401 § Link previews), already checked against the text. */
152
+ preview?: LinkPreview;
153
+ /**
154
+ * The message this one answers (`r`, WISP 401 § Replies), its line cleaned. Over the DHT only the id comes
155
+ * (`s` empty, `f` absent): the receiver finds the rest in its own history.
156
+ */
157
+ reply?: WireReply | {
158
+ i: string;
159
+ };
160
+ /** How many times it has been forwarded (`fw`, WISP 401 § Forwards); absent for a message written in this chat. */
161
+ forwarded?: number;
162
+ /** A status card (`sc`, WISP 405 · Status Cards), already checked; the text is its fallback. Live session only. */
163
+ card?: StatusCard;
164
+ }
165
+ /** Largest `paired-message` frame sent with a preview: a session fails on a frame over 60 KiB (`PairedSession`). */
166
+ export declare const MAX_PAIRED_MESSAGE_FRAME: number;
167
+ /**
168
+ * A `paired-message` frame. The preview (`pv`) is left out when the frame would pass `MAX_PAIRED_MESSAGE_FRAME`
169
+ * with it: the text matters, the card does not. A reply (`r`, WISP 401 § Replies) is a few hundred bytes at most
170
+ * and always goes, and so does a forwarded message's hop count (`fw`, WISP 401 § Forwards) and a status card (`sc`,
171
+ * WISP 405 · Status Cards), whose 8 KiB with the text's 16 stay well inside the frame.
172
+ */
173
+ export declare function pairedMessageFrame(id: string, ts: number, m: string, preview?: LinkPreview, reply?: WireReply, forwarded?: number, card?: StatusCard): string;
174
+ /**
175
+ * The transport a chat is set to reach and is not on yet (WISP 100, "A chosen transport not reached yet"): waited for,
176
+ * never failed. `by`: whose choice names it (absent: a policy alone, such as Fallback off, limits the chat to it).
177
+ */
178
+ export interface TransportWait {
179
+ transport: PairedTransport;
180
+ by?: "you" | "contact";
181
+ /**
182
+ * - `unknown`: the contact's app has not said whether it has it (no capability record read, no session lists it);
183
+ * - `starting`: the contact's record lists it, but there is no way to dial it yet (its endpoint is starting);
184
+ * - `connecting`: a switch to it is under way;
185
+ * - `unreachable`: both have it, and the last attempt did not connect (`error`, when this side knows);
186
+ * - `waiting`: both have it and nothing failed yet: the next attempt goes when the contact is there;
187
+ * - `contact-lacks`: the contact's latest record does not list it: its app does not have it;
188
+ * - `app-lacks`: this app does not run it (the contact chose it, or this side's adapter is gone).
189
+ */
190
+ reason: "unknown" | "starting" | "connecting" | "unreachable" | "waiting" | "contact-lacks" | "app-lacks";
191
+ /** The chat is live on another transport meanwhile (both allow a fallback); otherwise it is on the DHT. */
192
+ live?: PairedTransport;
193
+ /** Attempts that did not connect in a row, and why the last one did not, when this side dialled it. */
194
+ failures: number;
195
+ error?: string;
196
+ /** When the next attempt goes, when one is scheduled on this side. */
197
+ retryAt?: number;
198
+ }
199
+ /**
200
+ * The last attempt to go live that did not, as one side saw it (WISP 100, "Why a chat is not live"): shown so that a
201
+ * chat on the DHT is never a silent retry loop.
202
+ */
203
+ export interface LiveAttempt {
204
+ /** When it ended (ms since the epoch). */
205
+ at: number;
206
+ /** This side dialled it (the side with the lower rendezvous key, or a joiner), or answered the contact's offer. */
207
+ side: "dialled" | "answered";
208
+ /** Each transport tried and why it did not connect, in the order tried. An answering side knows only its own part. */
209
+ failed: {
210
+ transport: PairedTransport;
211
+ error: string;
212
+ }[];
213
+ /** Why nothing could be tried, when nothing was (no transport both apps have and can dial yet). */
214
+ reason?: string;
215
+ /** When this side dials again (it dials): about then, once the contact is seen. */
216
+ retryAt?: number;
217
+ }
218
+ export interface GhostLinkEvents {
219
+ onDhtDelivery?(view: DhtDeliveryView): void;
220
+ onDiscoveryError?(error: string | null): void;
221
+ onPeerProof?(frame: Record<string, unknown>): Promise<void>;
222
+ /** An `idp-*` identity-proof frame from the paired contact (only when both sides offer `identity-proof/1`). */
223
+ onIdentityProof?(frame: Record<string, unknown>): Promise<void>;
224
+ onTransportsChanged?(): void;
225
+ /**
226
+ * The contact chose a transport for this chat just now (its switch intent went up on the open session), or went
227
+ * back to automatic (its intent fell to 0). `apart`: heard with no session to raise an intent on, from its capability
228
+ * record, or from the first policy of a session it chose before (WISP 100, "A choice made while not live"); the
229
+ * owner may have told it already.
230
+ */
231
+ onPeerTransportChoice?(transport: PairedTransport | "automatic", apart?: boolean): void;
232
+ /**
233
+ * A switch to `target` could not connect and the session stayed where it was (both allow fallback). `reason` is
234
+ * known on the side that dialled; the other side learns only that it did not happen.
235
+ */
236
+ onTransportSwitchFailed?(target: PairedTransport, reason?: string): void;
237
+ /** The transport the chat waits for, or why, changed (`transportWait`); undefined once nothing is waited for. */
238
+ onTransportWait?(wait: TransportWait | undefined): void;
239
+ /** An attempt to go live ended without it (`liveAttempt`), or the chat went live (undefined). */
240
+ onLiveAttempt?(attempt: LiveAttempt | undefined): void;
241
+ /** A live transport switch completed: the session now runs over `to`, and nothing reconnected. */
242
+ onTransportSwitched?(from: PairedTransport | undefined, to: PairedTransport): void;
243
+ /** Round trip of a liveness ping on the open session, in milliseconds. */
244
+ onRtt?(ms: number): void;
245
+ onTransportDiscovery?(descriptors: TransportDescriptors, transports: PairedTransport[], fallback: boolean): Promise<void>;
246
+ /**
247
+ * With `packetTransports`: the member's packet said which transports its app runs on this link and how to dial them.
248
+ * Without `webrtc/1` among them, it has none, and a session takes native endpoints on this side too.
249
+ */
250
+ onPacketTransports?(transports: PairedTransport[], descriptors: TransportDescriptors): void;
251
+ /**
252
+ * With `packetTransports`: the member's packet has carried no `_tr` for `TRANSPORTS_GONE_MS` (link.ts), so its app
253
+ * publishes none, as one with WebRTC that runs no native endpoint on this link does. What an earlier packet said is
254
+ * forgotten here, and the owner forgets what it kept of it.
255
+ */
256
+ onPacketTransportsGone?(): void;
257
+ onPairingState?(state: PairingState): void;
258
+ /** How far a first pairing got (`pairingProgress` option): every change, up to `live`. */
259
+ onPairingProgress?(progress: PairingProgress): void;
260
+ onMessage?(message: IncomingMessage): void | Promise<void>;
261
+ onPresence?(presence: PeerPresence): void;
262
+ /** A paired contact's profile picture, already checked; `null` when they removed it. */
263
+ onPeerAvatar?(avatar: string | null): void;
264
+ /**
265
+ * The name a paired contact asked to be shown by, already checked; `null` when they have none (never set,
266
+ * removed, or not shared). Said on every session, so what arrives here is the contact's current choice.
267
+ */
268
+ onPeerNick?(nick: string | null): void;
269
+ onMessageReceipt?(id: string): void | Promise<void>;
270
+ /**
271
+ * A file's offer the contact said on the DHT floor (WISP 403 § Files), already checked: its bubble takes its place
272
+ * now, and its bytes come on the live session under the same wire id. Without this event it is dropped (receipted).
273
+ */
274
+ onFileAnnounced?(file: DhtFileAnnouncement & {
275
+ timestamp: number;
276
+ reply?: {
277
+ i: string;
278
+ };
279
+ forwarded?: number;
280
+ }, packet: DhtPacketFacts): void | Promise<void>;
281
+ /**
282
+ * What the contact's app says about held items (`hold/1`): whether it accepts them (from the handshake, or
283
+ * a `paired-hold` frame on the session) and the highest sequence it has held for this side, if it said.
284
+ */
285
+ onHold?(state: {
286
+ peerAllows: boolean;
287
+ peerTop?: number;
288
+ }): void | Promise<void>;
289
+ onPeerAck?(ackTimestamp: number): void;
290
+ onCallSignal?(signal: string): void;
291
+ /**
292
+ * The contact started or stopped typing (`typing/1`, WISP 401 § Typing), or said something new while it goes on
293
+ * (recording, thinking, a bot's status); only changes, never stored.
294
+ */
295
+ onPeerTyping?(typing: boolean, activity: TypingActivity | null): void;
296
+ /**
297
+ * The contact reacted to a message (`react/1`, WISP 401 § Reactions), already checked. True: confirm it (it was
298
+ * taken: shown, kept for its message, or older than what is shown); false: not now, it comes again.
299
+ */
300
+ onReaction?(reaction: WireReaction): boolean | Promise<boolean>;
301
+ /** The contact confirmed this side's reaction numbered `n`. */
302
+ onReactionReceipt?(n: number): void | Promise<void>;
303
+ /** The contact's DHT envelope said it took this side's reactions up to number `n`. */
304
+ onReactionsTaken?(n: number): void | Promise<void>;
305
+ /** Both sides offer `react/1` on the open session (true), or no longer (false). */
306
+ onReactionsSupport?(supported: boolean): void;
307
+ /**
308
+ * The contact edited one of its messages (`edit/1`, WISP 401 § Edits), already checked. True: confirm it now (it
309
+ * was shown, or was not newer, or its message is gone); false: not yet (its message is not here), and
310
+ * `confirmEdit` says so once it is.
311
+ */
312
+ onMessageEdit?(edit: WireEdit): boolean | Promise<boolean>;
313
+ /** The contact confirmed edit `e` of one of this side's messages. */
314
+ onEditReceipt?(id: string, e: number): void | Promise<void>;
315
+ /** Both sides offer `edit/1` on the open session (true), or no longer (false). */
316
+ onEditSupport?(supported: boolean): void;
317
+ /**
318
+ * The contact pinned a message, or unpinned (`pin/1`, WISP 401 § Pinned message), already checked. True: confirm it
319
+ * (taken, or older than the pin shown); false: not now, it comes again.
320
+ */
321
+ onPin?(pin: WirePin): boolean | Promise<boolean>;
322
+ /** The contact confirmed this side's pin numbered `n`. */
323
+ onPinReceipt?(n: number): void | Promise<void>;
324
+ /** Both sides offer `pin/1` on the open session (true), or no longer (false). */
325
+ onPinSupport?(supported: boolean): void;
326
+ /**
327
+ * The contact shared how to wake its closed web app (`wake/1`, WISP 401 § Wake-up push), already checked; null:
328
+ * it stopped sharing (forget it). Kept by the caller: it is what makes a wake-up possible while the contact is away.
329
+ */
330
+ onPeerWake?(target: WakeTarget | null): void;
331
+ /** Both sides offer `wake/1` on the open session (true), or no longer (false): the moment to share this side's. */
332
+ onWakeSupport?(supported: boolean): void;
333
+ /**
334
+ * The contact's app opened, closed or sent data in one of this chat's mini-apps (`apps/1`, WISP 1200 § In a chat),
335
+ * already checked against the receiver's limits; or, as a `close` with `offline`, the session ended while it had one
336
+ * open. Never stored.
337
+ */
338
+ onAppFrame?(event: AppFrameEvent): void;
339
+ /** Both sides offer `apps/1` on the open session (true), or no longer (false). */
340
+ onAppsSupport?(supported: boolean): void;
341
+ onStatus?(status: LinkStatus): void;
342
+ onDataLinkState?(state: DataLinkState): void;
343
+ /** What a WebRTC attempt of this link said about direct connections from this device (`directPath.ts`). */
344
+ onDirectEvidence?(evidence: DirectEvidence): void;
345
+ /**
346
+ * WebRTC here refused this side's answers in a row through every pause after them (`ANSWERS_REFUSED_PAUSES`): the next
347
+ * offer waits the backoff of failed dials, minutes, while the contact is there.
348
+ */
349
+ onAnswersRefused?(): void;
350
+ /** The contact's packet came between two reads of its record: its clock against this one (`LinkSessionEvents.onPeerClock`). */
351
+ onPeerClock?(packetAt: number, readBefore: number, readAt: number): void;
352
+ onPoll?(poll: {
353
+ polling: boolean;
354
+ nextInMs: number;
355
+ }): void;
356
+ /** The peer is sending a file. Return where to put it, or null (or a reason) to refuse. */
357
+ onFileStored?(file: FileInfo): Promise<string | undefined>;
358
+ onFileIncoming?(file: FileInfo): FileSink | string | null;
359
+ onFileProgress?(fileId: string, transferred: number, direction: "in" | "out"): void;
360
+ onFileComplete?(fileId: string, direction: "in" | "out"): void;
361
+ onFileFailed?(fileId: string, reason: string, direction: "in" | "out"): void;
362
+ /** A files/3 frame (`FILE_FRAMES`), only while both sides agreed `files/3` on the open session. */
363
+ onFilesFrame?(frame: Record<string, unknown>): void | Promise<void>;
364
+ /**
365
+ * files/3 can flow (a session agreed it and is open), or no longer can. Said again, open, after a live
366
+ * transport switch: frames on the old channel may be lost, and offering again puts both sides in step.
367
+ */
368
+ onFilesSession?(open: boolean): void;
369
+ onPaymentRequest?(request: PaymentRequest): void | Promise<void>;
370
+ /** A contact asking to pay this side (paired chats): answer with a request carrying the ask's id. */
371
+ onPaymentAsk?(ask: PaymentAsk): void | Promise<void>;
372
+ onPayment?(payment: Payment): void | Promise<void>;
373
+ onPaymentResult?(result: PaymentResult): void | Promise<void>;
374
+ /** A `group-*` frame (WISP 900) from the peer, only while both sides announced `paired-groups`. */
375
+ onGroupFrame?(frame: Record<string, unknown>): void | Promise<void>;
376
+ /** Group frames can flow (both announced), or no longer can. */
377
+ onGroupsSupport?(supported: boolean): void;
378
+ /**
379
+ * A frame between two of a person's devices (WISP 06, `deviceLink.ts`), on a device link only, and only while both
380
+ * ends announced the capability its type travels under.
381
+ */
382
+ onDeviceFrame?(frame: DeviceFrame): void | Promise<void>;
383
+ /** The device capabilities both ends announced on the open session changed: what is agreed now. */
384
+ onDeviceCapabilities?(agreed: DeviceCapability[]): void;
385
+ /**
386
+ * A session was refused because the other end authenticated with another participation key than the one pinned.
387
+ * A device's one-time enrollment link (WISP 06 § Adding a device) tells the person that a second device tried its code.
388
+ * Also once for each further key that signs a signal in the other end's packet: every holder of the code writes that
389
+ * one packet, so a second key there is a second device, whether or not a key was pinned yet.
390
+ */
391
+ onPeerKeyRefused?(): void;
392
+ }
393
+ /** For each way of paying, the networks (real money, test coins) this side has a wallet on. */
394
+ export type PaymentNetworks = Partial<Record<PaymentMethodName, ("mainnet" | "testnet")[]>>;
395
+ /** A `paired-payments` networks map from the contact, or null when it is not a valid one (it is then ignored). */
396
+ export declare function parsePaymentNetworks(value: unknown): PaymentNetworks | null;
397
+ export interface GhostLinkOptions {
398
+ /** Ways of paying this chat allows. One that is off is not offered in the handshake, sent or accepted. Absent: allowed. */
399
+ paymentMethods?: Partial<Record<PaymentMethodName, boolean>>;
400
+ /**
401
+ * The networks of this side's wallets, per way of paying: said with the methods on the open session, so the
402
+ * contact offers only cards whose networks meet. Older apps ignore it.
403
+ */
404
+ paymentNetworks?: PaymentNetworks;
405
+ arkPaymentsSupport?: boolean;
406
+ usdtPaymentsSupport?: boolean;
407
+ barkPaymentsSupport?: boolean;
408
+ /** Announce private groups (WISP 900) on the open session. Announced after the handshake, like `paired-payments`, so a full offer stays within what older apps accept. */
409
+ groupsSupport?: boolean;
410
+ /** Offer `hold/1`: accept items held for this side, and hold items for the contact while it is away. */
411
+ holdSupport?: boolean;
412
+ /** Offer `calls/1` on paired sessions: this app can place and take calls (WebRTC media and capture). */
413
+ callsSupport?: boolean;
414
+ /** Why this app cannot call, when `callsSupport` is off and the platform can say more (what to install). */
415
+ callsMissing?: string;
416
+ /** Offer `services/1` on paired sessions: this app can serve granted local web apps and open the contact's. */
417
+ servicesSupport?: boolean;
418
+ /** Offer `files/3` on paired sessions: files of any size, offered, resumed and checked (`chatFiles.ts`). */
419
+ largeFilesSupport?: boolean;
420
+ /** Offer `typing/1` on paired sessions: say and show when either side is writing (1:1 chats, not group edges). */
421
+ typingSupport?: boolean;
422
+ /** Offer `react/1` on paired sessions: reactions to messages (1:1 chats, not group edges). */
423
+ reactionsSupport?: boolean;
424
+ /** Offer `edit/1` on paired sessions: sent texts can be edited (1:1 chats, not group edges). */
425
+ editSupport?: boolean;
426
+ /** Offer `pin/1` on paired sessions: a pinned message (1:1 chats, not group edges). */
427
+ pinSupport?: boolean;
428
+ /** Offer `status-card/1` on the paired session: this app shows status cards (WISP 405 · Status Cards). */
429
+ statusCardSupport?: boolean;
430
+ /** Offer `buttons/1` on the paired session: this app shows and presses message buttons (WISP 406 · Message Buttons). */
431
+ buttonsSupport?: boolean;
432
+ /** Offer `wake/1` on paired sessions: this app wakes a contact's closed web app with a push (1:1 chats, not group edges). */
433
+ wakeSupport?: boolean;
434
+ /**
435
+ * Offer `upgrade/1` on paired sessions (1:1 chats): a session live on a relayed transport, nobody having chosen it,
436
+ * moves once to a direct one ranked first; and back after an absence, a relayed transport is knocked on at once too,
437
+ * where the contact's capability record says it moves as well (`peerUpgrades`).
438
+ */
439
+ upgradeSupport?: boolean;
440
+ /**
441
+ * Offer `apps/1` on paired sessions (1:1 chats, not group edges): mini-apps talk to the same app on the contact's
442
+ * side (WISP 1200 § In a chat). Behind the apps feature flag.
443
+ */
444
+ appsSupport?: boolean;
445
+ /**
446
+ * The apps this side has open in this chat (chat app id to version), kept by the caller across this link's restarts.
447
+ * Each new session says `open` for each. Without it the link keeps its own.
448
+ */
449
+ appsOpen?: Map<string, string>;
450
+ /** How long the contact's open apps are held across a session change (`APP_RESUME_GRACE_MS`); tests shorten it. */
451
+ appResumeGraceMs?: number;
452
+ /** The contact's capability record, as last read, says `upgrade/1` (WISP 03). */
453
+ peerUpgrades?: () => boolean;
454
+ /**
455
+ * Whether this device has no network now. A native dial that fails then says nothing about its transport, so it
456
+ * counts toward no demotion. By default the browser's `navigator.onLine`; a host that cannot tell is never offline.
457
+ */
458
+ offline?: () => boolean;
459
+ /**
460
+ * A device link (WISP 06): the capabilities it announces on the open session, and so the device frames it carries
461
+ * (`sendDeviceFrame`, `onDeviceFrame`). Never given for a chat or a group's link, which drop every device frame.
462
+ */
463
+ deviceCapabilities?: readonly DeviceCapability[];
464
+ dht?: {
465
+ state?: DhtDeliveryState;
466
+ save(state: DhtDeliveryState): Promise<void>;
467
+ pollMs?: number;
468
+ /** A chat already paired, started again: its first control envelope waits this long (`DhtDelivery`). */
469
+ firstControlAfterMs?: number;
470
+ /** This side's capability-record revision, told in every envelope (WISP 03). */
471
+ capsRev?(): number | undefined;
472
+ /** An envelope from the contact named this revision of its capability record. */
473
+ peerCapsRev?(rev: number): void;
474
+ /** Whether the contact's capability record accepts DHT text; absent or unknown: it does. */
475
+ peerAcceptsText?(): boolean;
476
+ /** Whether the contact's capability record takes a file's offer on the floor (`dht-file/1`); absent: it does not. */
477
+ peerAcceptsFile?(): boolean;
478
+ /** This side's reactions the contact has not confirmed, oldest first: they ride on the envelopes. */
479
+ reactions?(): readonly WireReaction[];
480
+ };
481
+ rtcAvailable?: boolean;
482
+ /** `automatic`: the chat follows the app's rule (no transport chosen for it); `preferred` is then the rule's. Absent: automatic unless `preferred` is given. */
483
+ native?: {
484
+ peerDescriptors?: TransportDescriptors;
485
+ peerTransports?: PairedTransport[];
486
+ peerFallback?: boolean;
487
+ preferred?: PairedTransport;
488
+ fallback?: boolean;
489
+ automatic?: boolean;
490
+ };
491
+ params: LinkParams;
492
+ pairing?: {
493
+ credentials: PairingCredentials;
494
+ pinPeer: (key: string, signedSignals?: boolean) => Promise<void>;
495
+ verifyPeer?: (key: string) => Promise<void>;
496
+ trustOnFirstUse?: boolean;
497
+ };
498
+ /**
499
+ * A chat that was never paired: follow its first pairing (`onPairingProgress`), and pace its attempts
500
+ * for a contact who is right there. `startedAt`: when the invite was made or joined.
501
+ */
502
+ pairingProgress?: {
503
+ role: PairingRole;
504
+ startedAt: number;
505
+ };
506
+ /** When the chat was made, for a saved one: a contact never seen is awaited from then, not from this start (`LinkSessionOptions.awaitingSince`). */
507
+ madeAt?: number;
508
+ transport: PkarrTransport;
509
+ nick?: string;
510
+ /** This side's profile picture (a small JPEG data URL), told to a paired peer directly. */
511
+ avatar?: string;
512
+ lastSeenTimestamp?: number;
513
+ pollIntervals?: PollIntervals;
514
+ /**
515
+ * The transport this chat was live on when the app last ran (it quit, or crashed, with the session up). The contact is
516
+ * probably still there, holding a session that is dead now: that transport is dialled first, and a native one is
517
+ * dialled at once by either side, not only by the side whose turn it is (WISP 100, "Back after a restart").
518
+ */
519
+ resume?: PairedTransport;
520
+ /**
521
+ * When the session that was live when this app last ran began (ms). A contact's offer made before it is the one that
522
+ * set that session up, or an older one, read from a relay that never got the packet clearing it: it is not answered,
523
+ * and a resumed link dials instead. An offer made after it (the contact noticed the session go, during a long
524
+ * downtime) is answered as any. Unknown (never live, a log lost): every offer is taken as before (bug hunt r7a).
525
+ */
526
+ resumeFloor?: number;
527
+ /**
528
+ * Only this link's two ends can write its records: a group's edge or entry session, whose keys come from the two
529
+ * members' own keys. A chat's records are under keys from its invite, which whoever holds a copy of it can write.
530
+ */
531
+ ownRecords?: boolean;
532
+ /**
533
+ * Open the data link on its own whenever the peer is online, instead of on
534
+ * first use. Chat and call signaling then travel peer to peer and Pkarr is
535
+ * only polled once a minute, which is what keeps relays happy.
536
+ */
537
+ autoConnect?: boolean;
538
+ /** When its first packet goes out (`LinkSessionOptions.firstPublish`): after its first look, the side that dials puts its offer in it. */
539
+ firstPublish?: "at-start" | "after-first-poll";
540
+ /**
541
+ * A link for one exchange, closed right after it (a group's entry session): once connected, it leaves
542
+ * its offer or answer in its packet rather than publishing again to clear it.
543
+ */
544
+ oneShot?: boolean;
545
+ /**
546
+ * A group's link (an edge, an entry session), which has no capability record: once this side runs a native endpoint on
547
+ * it, its transports and how to dial them ride its own packet (`_tr`), and the member's are read from its packet
548
+ * (WISP 902 § Transports). The owner starts endpoints only where one side has no WebRTC (`onPacketTransports`).
549
+ */
550
+ packetTransports?: boolean;
551
+ /**
552
+ * With `packetTransports`: this side published a `_tr` on this link before (in an earlier run of the app). It goes on
553
+ * saying what it runs now, with or without a native endpoint: the member's app kept the last value it read, and a
554
+ * packet with no `_tr` at all takes nothing back from an app that acts only on one that is there (WISP 902 § Transports).
555
+ */
556
+ packetTransportsSaid?: boolean;
557
+ createPeerConnection: () => RTCPeerConnection;
558
+ localFetch: LocalFetch;
559
+ /** Everything this peer currently offers on this link. */
560
+ getServices: () => ServiceAd[] | undefined;
561
+ /** Web apps a paired contact may reach: told to that contact alone, on the open session, never published. */
562
+ getPairedServices?: () => ServiceAd[];
563
+ /** Resolves an advertised `http` service id to its local target. */
564
+ getHostedHttpService: (id: string) => HostedHttpService | undefined;
565
+ events?: GhostLinkEvents;
566
+ }
567
+ /**
568
+ * What a link says when its connection details could not go out: the transport's reason (the Desktop's Rust client
569
+ * rejects with a string, not an Error), and when it is tried again, the soonest a relay is asked ("asked again in N s").
570
+ */
571
+ export declare function publishFailure(error: unknown): string;
572
+ export declare class GhostLink {
573
+ readonly session: LinkSession;
574
+ private readonly dht;
575
+ private deliveryMode;
576
+ private securityRejected;
577
+ readonly dataLink: DataLink;
578
+ private readonly options;
579
+ private channel;
580
+ private endpoints;
581
+ private activeBinding?;
582
+ private dialing;
583
+ /** A joiner's dial made as the link starts (`dialEarly`): its offer goes once the first look finds the inviter. */
584
+ private dialGate?;
585
+ private firstLookDone?;
586
+ private dhtPinGrace;
587
+ /** Native attempts that failed in a row, and transports demoted until when (WISP 100, demotion). */
588
+ private nativeFailures;
589
+ private demotedUntil;
590
+ private connectionEpoch;
591
+ private switchAllowedUntil;
592
+ private switchAck;
593
+ private readonly switcher;
594
+ /** `plan`: a switch both sides agreed; without one, a replacement the contact dialled (`attachReplacement`). */
595
+ private candidate;
596
+ private candidateEpoch;
597
+ /** Channels a switch replaced, closed after `SWITCH_RETIRE_MS` (or at once on disconnect). */
598
+ private retiring;
599
+ private rtcCandidateWaiter;
600
+ private transitionTarget?;
601
+ private transitionError?;
602
+ private applicationOpen;
603
+ private stopped;
604
+ /** Connection details this side could not publish were reported as a pairing error, which the next packet out ends. */
605
+ private signalPublishFailed;
606
+ private peerDescriptors;
607
+ private peerTransports?;
608
+ /** A group link: this side published a `_tr` on it, in this run or an earlier one (`packetTransportsSaid`). */
609
+ private saidTransports;
610
+ /** A group link: what is known of the member's transports came from its packet (`_tr`), read now or kept from before. */
611
+ private peerPacketSaid;
612
+ private peerFallback;
613
+ private preferred;
614
+ private fallback;
615
+ /** No transport chosen for this chat: `preferred` is the app's rule. */
616
+ private automatic;
617
+ /** What the contact's latest capability record says its app runs (WISP 03); unknown until one is read. */
618
+ private peerRecordTransports?;
619
+ /**
620
+ * The contact's explicit choice for this chat as last heard, from its capability record or a session's switch
621
+ * intent; none on Automatic, or before either said (WISP 100, "A choice made while not live").
622
+ */
623
+ private peerChoice?;
624
+ /** The attempt to go live under way on this side, and what failed in it so far. */
625
+ private attempt;
626
+ private lastAttempt?;
627
+ /** The transport the chat waits for (WISP 100): attempts that failed in a row, the last error, the next retry. */
628
+ private waiting;
629
+ /** Why the target of the switch this side dialled did not connect, when a later choice may still carry the chat. */
630
+ private switchMissed?;
631
+ private paired;
632
+ private pairedPending;
633
+ private httpHost;
634
+ /** HTTP to and from shared web apps over a paired session. */
635
+ private pairedHttp;
636
+ private httpClient;
637
+ private files;
638
+ private pairedFiles;
639
+ private peerServicesOverride;
640
+ /** A paired peer's name arrives over the channel; nothing about it is published. */
641
+ /** Ways of paying the contact allows, as it last said on this session; null until it does. */
642
+ private peerPaymentMethods;
643
+ /** The contact's networks per way of paying, as it last said; null while it said none (an older app). */
644
+ private peerNetworks;
645
+ /** The contact's word on held items on this session; null until it says. */
646
+ private peerHoldOverride;
647
+ private peerNickOverride;
648
+ /** Group protocol versions the peer announced on this session; null until it does. */
649
+ private peerGroupVersions;
650
+ /** What each side announced after the handshake (`paired-capabilities`): calls, services. */
651
+ private readonly sessionCapabilities;
652
+ private readonly pairedCalls;
653
+ /** Typing on this session (`typing/1`): when to say `start` again, and the contact's word with its timeout. */
654
+ private readonly typingSender;
655
+ private readonly typingReceiver;
656
+ /** Mini-apps on this session (`apps/1`): this side's open apps (kept across sessions), the peer's, the limits. */
657
+ private readonly apps;
658
+ /** Reaction frames the contact may send per window; the rest go unconfirmed and come again. */
659
+ private readonly reactionsReceived;
660
+ /** Pin frames the contact may send per window; the rest go unconfirmed and come again. */
661
+ private readonly pinsReceived;
662
+ /** Edit frames the contact may send per window; the rest go unconfirmed and come again. */
663
+ private readonly editsReceived;
664
+ private readonly wakeReceived;
665
+ private livenessTimer;
666
+ private peerAnswersPings;
667
+ /** When the ping awaiting its pong went, and the round trip last measured on this session. */
668
+ private pingSentAt;
669
+ private rtt?;
670
+ /** The contact's transport policy as last seen on this session, to tell its explicit choices apart. */
671
+ private peerPolicySeen;
672
+ private unansweredPings;
673
+ /**
674
+ * Pings sent on this session and pongs heard on it, counted from its start: the contact answers each ping in the order
675
+ * frames come, so the pong to ping n says it handled everything sent before it (`handled`).
676
+ */
677
+ private pingsSent;
678
+ private pongsHeard;
679
+ /** The liveness ping whose pong measures the round trip: its number in `pingsSent`. */
680
+ private rttPing;
681
+ /** `handled` callers, each waiting for the pong to its ping. */
682
+ private handledWaiters;
683
+ /** The last ping's `PONG_WAIT_MS`: running until something comes back from the contact. */
684
+ private pongWait;
685
+ /** The last ping's wait ran out with nothing back, and nothing came since (`restartedRedial`). */
686
+ private pongLate;
687
+ private openWaiters;
688
+ /** Set while a WebRTC attempt this side dialled is pending: the ranked transports to try if it fails. */
689
+ private afterRtc?;
690
+ /** When the transports after WebRTC are dialled while its offer is still out (`race`). */
691
+ private raceTimer;
692
+ /** Pauses taken after a run of refused answers since WebRTC last opened, and the one under way (`ANSWERS_REFUSED_PAUSES`). */
693
+ private refusedPauses;
694
+ private refusedPause;
695
+ /** Set while `race` dials: the offer ending meanwhile is followed up by the race. */
696
+ private racing;
697
+ /**
698
+ * The WebRTC offer this side's dial made last, with fallback allowed: what a transport that comes up meanwhile joins.
699
+ * `resume`: the dial that made it is this side back after an absence, over WebRTC (`resuming`); `woke`: the absence
700
+ * was the app's in the background, not a restart (`resumeAfterAbsence`).
701
+ */
702
+ private offered?;
703
+ /** The attempt (its epoch) whose direct transports were knocked on as its offer went out (`knockEarly`), and whether that is under way. */
704
+ private knockedEarly;
705
+ private knockingEarly;
706
+ /** When that offer's answer was applied (`RACE_ANSWERED_MS`); 0 while the data link is not connecting on it. */
707
+ private answeredAt;
708
+ /** This side's offer is out unanswered, or answered and not connected yet: what is ranked after WebRTC may race it. */
709
+ private get offerOut();
710
+ /** The attempt (`connectionEpoch`) in which the data link began answering the contact's offer. */
711
+ private answeringEpoch;
712
+ /** Set while a dial waits for its WebRTC offer to be made: ends that wait, the contact's offer being answered instead. */
713
+ private offerReplaced?;
714
+ private lastAutoConnectAt;
715
+ private autoConnectFailures;
716
+ /** The look due when a failed dial's backoff ends (`lookAtRetry`). */
717
+ private retryLook;
718
+ /** This side's offer is out to the data link and has not reached the relays yet. */
719
+ private offerUnsent;
720
+ /** The last dial ended with its offer never out (`offerUnsent`): the contact saw nothing of it. */
721
+ private dialUnseen;
722
+ /** Native transports a record just read listed with no way to dial them (`record-undescribed`), until one describes them again. */
723
+ private readonly undescribed;
724
+ /**
725
+ * The native dial under way (`dialNative`): its attempt, its transport, the endpoint it went to (`redescribedDial`),
726
+ * and whether it started with this device offline (`networkBack`).
727
+ */
728
+ private nativeDial;
729
+ /** When the device's network last came back (`wake({ network: true })`): a dial under way across it is no failure. */
730
+ private networkBackAt;
731
+ /** The peer's packet I last looked fast for its offer after (its timestamp): once per packet. */
732
+ private offerAwaitedFor;
733
+ /** Whether the stream was blocked (DHT-only on either side) when last looked at. */
734
+ private streamWasBlocked;
735
+ /** The contact's latest `_rtc` signal while the stream was blocked. */
736
+ private heldSignal;
737
+ /** The link packet of a DHT-only contact its mailbox was last read early for (its timestamp): once per packet. */
738
+ private leftDhtSeenFor;
739
+ /** The first pairing of this chat, while it is one (`pairingProgress` option, no peer key yet). */
740
+ private readonly tracker;
741
+ private lastDataLinkState;
742
+ /** When an inviter first saw the joiner on the network (0: not yet). */
743
+ private peerSeenAt;
744
+ /** When the channel carrying the chat now was attached. */
745
+ private channelSince;
746
+ /** When the contact last sent something other than the session's upkeep (`QUIET_FRAMES`) on a session. */
747
+ private activityAt;
748
+ /** Set while `yieldEndpoint` ends the session to let its listener go: nothing dials meanwhile. */
749
+ private yielding;
750
+ /**
751
+ * The contact said goodbye on the live session (`paired-bye`): its app is going away, likely to restart. Its packet
752
+ * then was `packet`; it is dialled again once a newer one shows it back, or after `until`.
753
+ */
754
+ private departed;
755
+ /** The contact's link packet last seen (its timestamp), to tell a new one from the same one read again. */
756
+ private peerPacketSeen;
757
+ /** A live session ended without this side ending it (`peerLost`): until when the contact's next new packet is news. */
758
+ private lostUntil;
759
+ /** Counts the signals a signer was asked to sign: only the latest one goes out. */
760
+ private signalTurn;
761
+ /** Puts this side's packet out again as it is: another writer of its key may have replaced it. */
762
+ republish(): void;
763
+ /** The keys that signed a signal in the other end's packet, on a link that tells of refused keys (`onPeerKeyRefused`). */
764
+ private signalSigners;
765
+ /**
766
+ * A one-time enrollment link (WISP 06 § Adding a device: one session per invite): every device that reads the code
767
+ * writes the same packet, each signing its signals with its own device signing key, and the later one replaces the
768
+ * earlier. A validly signed signal by a key other than the one pinned, or than the first one seen there, is a second
769
+ * device on the code: said once per key, before a pin as after it.
770
+ */
771
+ private noteSignalSigner;
772
+ /** A signal ready to go: on the live session during a switch to WebRTC, in this side's packet otherwise. */
773
+ private signalOut;
774
+ /** This app is going away (`depart`): no more dials. */
775
+ private leaving;
776
+ /** `resume` still to act on: the first dial after the start goes to it, and a native one is knocked on. */
777
+ private resuming;
778
+ /** Until then, a dial waits for the native endpoint `resuming` names to start (it is knocked on as it does). */
779
+ private resumeWaitUntil;
780
+ /** What the last live session ran on, kept after it ended: a wake resumes on it (`resumeAfterAbsence`). */
781
+ private lastLiveOn;
782
+ /** `resuming` is a wake's, not a restart's. */
783
+ private resumingWoke;
784
+ /** Until then, a session that ends was lost while the app was away (`WAKE_LOST_MS`). */
785
+ private wokeUntil;
786
+ constructor(options: GhostLinkOptions);
787
+ get myPubKeyZ32(): string;
788
+ /** The first pairing's stages, read off the data link's states. */
789
+ private trackDataLink;
790
+ /** How far the first pairing got; absent for a chat that was paired before, or has no `pairingProgress`. */
791
+ get pairingProgress(): PairingProgress | undefined;
792
+ /**
793
+ * A contact's offer from before the session that was live when this app last ran began (`resumeFloor`): answering
794
+ * it held the resumed link on a connection the contact no longer offers, until ICE gave up (about 30 s), and its
795
+ * resume dial never went (bug hunt r7a). Dropped; the resumed link dials when it sees the contact.
796
+ *
797
+ * The floor is this device's clock and the offer's time is the contact's: the two are compared only for an offer
798
+ * the first read of this run found, which nothing else dates. One this run saw arrive (`sight`: the contact's record
799
+ * did not have it at an earlier read, and it is not dated before the contact's packet that read found) was made
800
+ * since this app is back. Held against the floor, the offers of a contact whose clock is behind were all dropped
801
+ * until that clock passed the moment the last session began: minutes without a live chat after a restart.
802
+ */
803
+ private predatesLastSession;
804
+ /** The time of the offer the contact's packet carries, as last read (verified as `handleRtcSignal` does); null for none. */
805
+ private peerOfferTs;
806
+ private handleRtcSignal;
807
+ /**
808
+ * Leaving DHT-only takes both sides: each is blocked from a live link until it has seen the other one
809
+ * leave too. The moment it is not, the link is dialled or answered at once: the wait between failed
810
+ * attempts starts over, the contact's offer (or its presence) is looked for fast, and an offer that
811
+ * came in while blocked is answered now instead of timing out on the contact's side (90 s, then its
812
+ * backoff) before it offers again.
813
+ */
814
+ private streamBlockChanged;
815
+ /**
816
+ * A DHT-only contact runs no link session, so it does not advertise itself on the link's key: a fresh
817
+ * packet there that does is it leaving DHT-only. Its mailbox, which says so, is read now rather than at
818
+ * the next poll, and at the DHT pace for a while after: the link packet can reach a relay before the
819
+ * envelope saying so does (back from `chat disconnect --hold`), and a read that still finds DHT-only
820
+ * would otherwise keep the chat off a live link until the next background read, 30 s on.
821
+ */
822
+ private peerMayHaveLeftDht;
823
+ /**
824
+ * The contact dials (a WebRTC offer signed by its pinned key, or a connection on a native endpoint) while its
825
+ * mailbox last said DHT-only: it has left, and the envelope saying so is on its way. The offer's packet often has no
826
+ * room for the presence `peerMayHaveLeftDht` looks at, so the mailbox is read now and at the DHT pace for a while
827
+ * here too. The offer is kept and answered, and the dial taken, once that read unblocks the stream. False when
828
+ * something else blocks it (this side is DHT-only, the contact is not pinned, or the offer is not the contact's).
829
+ */
830
+ private peerDialsFromDht;
831
+ get isDataLinkOpen(): boolean;
832
+ private currentTransportAllowed;
833
+ /**
834
+ * A packet went out after connection details could not be: the session kept trying (every few seconds), so the
835
+ * error that was reported is over and the pairing carries on from where it is.
836
+ */
837
+ private publishRecovered;
838
+ private emitPairingState;
839
+ get presence(): PeerPresence;
840
+ private get streamBlocked();
841
+ /**
842
+ * A stream authenticated a participation key other than the pinned one: a security rejection, which stops the chat
843
+ * on both layers until the person acts (WISP 400), never a reason to fall back to the other path. Only a stream can
844
+ * prove it: the DHT mailbox and the link's signals are written under keys any copy of the invite derives, so another
845
+ * key there is ignored instead.
846
+ */
847
+ private keyStopped;
848
+ /** A connection whose failure to authenticate says nothing about the contact: dialled in on a pinned chat. */
849
+ private unproven;
850
+ /**
851
+ * A session that started before the pin and was refused for another key: the pin came by another path meanwhile (the
852
+ * DHT's first contact), and whoever this session reached held only a copy of the invite. It proves nothing either.
853
+ */
854
+ private pinnedSince;
855
+ get textDelivery(): "stream" | "dht" | "unavailable";
856
+ /** A session is ready, but on a transport the policies do not allow: it coordinates a switch and carries nothing else. */
857
+ private get sessionBlocked();
858
+ validateText(text: string, timestamp: number, id: string, reply?: WireReply): string | null;
859
+ get canSendText(): boolean;
860
+ get dhtDelivery(): DhtDeliveryView | undefined;
861
+ /** The chat is on screen: on the DHT its mailbox is read at the signaling pace (WISP 403, poll pace). */
862
+ setChatActive(active: boolean): void;
863
+ private emitDeliveryState;
864
+ setDeliveryMode(mode: DeliveryMode): Promise<void>;
865
+ start(): void;
866
+ /**
867
+ * A joiner's offer is gathered as the link starts, while its first look at the inviter's record is under way, and goes
868
+ * once that look finds the inviter (`dialGate`): the two used to come one after the other, the read (0.15 to 0.8 s)
869
+ * then the gathering (0.2 s to 2 s).
870
+ */
871
+ private dialEarly;
872
+ stop(announce?: boolean): Promise<void>;
873
+ /** Opens the data link if needed and resolves once it is usable. */
874
+ connect(timeoutMs?: number): Promise<void>;
875
+ /** Closes what a switch replaced once the contact has had time to move too. */
876
+ private retire;
877
+ /**
878
+ * The WebRTC session a switch moved off is still retiring (`SWITCH_RETIRE_MS`): its data link is open, and a new offer
879
+ * cannot go until it closes. Resolves once it has (at once when none is).
880
+ */
881
+ private rtcRetired;
882
+ private closeRetired;
883
+ disconnect(): void;
884
+ /** What the contact's app can use on this link, as it last said (on the open session, or remembered). */
885
+ get peerAvailableTransports(): PairedTransport[] | undefined;
886
+ /** The open session goes through relays (WISP 100, "Relayed"): their hosts, this side's first. */
887
+ get relayedPath(): {
888
+ relays: string[];
889
+ } | undefined;
890
+ /** The round trip last measured on the open session; unknown until a ping was answered. */
891
+ get rttMs(): number | undefined;
892
+ /**
893
+ * The transports a session with this contact would cross a relay on: those either side reaches only
894
+ * through one (a browser's HyperDHT or Iroh), per the latest descriptors both sides gave.
895
+ */
896
+ get relayedTransports(): PairedTransport[];
897
+ /** This side's native descriptors, for its capability record (WISP 03): what a contact dials without WebRTC first. */
898
+ get nativeDescriptors(): TransportDescriptors;
899
+ /**
900
+ * The contact's capability record named its native transports and how to dial them: a chat whose WebRTC never
901
+ * connected can still try Iroh or HyperDHT. `fresh`: a record just read, the contact's latest word, so a way to dial
902
+ * it gives (a relay its Iroh endpoint homed on after it started, a new endpoint) replaces the one known. Otherwise (the
903
+ * record kept from before) it only fills what is missing: what a session said is fresher, and transcript-bound.
904
+ */
905
+ learnPeerTransports(transports: PairedTransport[], descriptors: TransportDescriptors, fresh?: boolean): void;
906
+ /** When `dialOnNews` last let a dial go before its wait was over. */
907
+ private lastNewsDialAt;
908
+ /**
909
+ * A chat's listener came up, or the contact's record describes again an endpoint it said was down: the next dial goes
910
+ * now rather than after the wait between attempts, once per that wait. An endpoint registered again and again (a
911
+ * listener lost and started anew) or a record going down and up again would otherwise dial every time, each a native
912
+ * dial, Rust work on a Desktop (a Linux Desktop's idle CPU, 2026-10-01). The failures keep counting.
913
+ */
914
+ private dialOnNews;
915
+ /**
916
+ * This side's capability record has a new revision: a DHT envelope names it now, so the contact reads it (WISP 03).
917
+ * Only on the DHT with the contact pinned. A live session carries the same news itself, and before the pin the
918
+ * contact reads the record when it pins; either way an envelope would only spend a relay request, the budget the
919
+ * chat's signalling and held items need.
920
+ */
921
+ announceCapsRevision(): void;
922
+ /** The transport chosen for this chat on this side, for its capability record; none on Automatic. */
923
+ get choice(): PairedTransport | undefined;
924
+ /**
925
+ * The contact's explicit choice as its capability record names it (WISP 100, "A choice made while not live"): how a
926
+ * contact with no session hears of it. `fresh`: a record just read. One that names another choice than the last heard
927
+ * is told (`onPeerTransportChoice`, apart) and dialled first from now on. With a session open, its intents are the
928
+ * contact's word, not a record that may be older; the record kept from before only sets where to start.
929
+ */
930
+ learnPeerChoice(choice: string | undefined, fresh?: boolean): void;
931
+ /**
932
+ * The explicit choice that stands with no session to agree in (WISP 100, "A choice made while not live"): this
933
+ * side's, or the contact's last heard. When both chose and they differ, the lower rendezvous key's, as a tie is
934
+ * settled on a session. None when neither chose.
935
+ */
936
+ private get choiceApart();
937
+ /** Something decides where the chat dials first now: the next attempt goes at once, not after the wait failures built up. */
938
+ private dialNow;
939
+ /**
940
+ * Where the chat is set to go and is not yet (WISP 100, "A chosen transport not reached yet"). With a session, the
941
+ * agreement of both policies; without one, a limit of this side's (Fallback off), or else an explicit choice (this
942
+ * side's, or the contact's from its record): otherwise any transport will do, and the chat is simply retrying live.
943
+ */
944
+ private wanted;
945
+ /** The transport this chat waits for, and why; absent when it is on it, or nothing limits where it goes. */
946
+ get transportWait(): TransportWait | undefined;
947
+ /**
948
+ * An attempt to reach `target` did not connect. The chat waits for it, and the side that plans switches tries again
949
+ * on the background pace (`schedule`: with a session; without one the dial's own pace does). True the first time
950
+ * for this wait: a fallback that kept the chat live is said once, later attempts are quiet.
951
+ */
952
+ private unreached;
953
+ /** A dial with no session failed while the chat waits for a transport: counted there. True when it waits. */
954
+ private dialFailed;
955
+ /** The next attempt for the transport the chat waits for, on the background pace. */
956
+ private retryWait;
957
+ /** Something new about the transport waited for (the contact's record lists it, or says how to dial it): try now. */
958
+ private waitNews;
959
+ private clearWait;
960
+ /** The chat reached what it waited for, or waits for something else now (a new choice, Automatic, a policy change). */
961
+ private syncWait;
962
+ private waitSaid;
963
+ /** Tells the owner when the wait's view changed (its reason, failures, next retry). */
964
+ private notifyWait;
965
+ get availableTransports(): PairedTransport[];
966
+ private transportOffer;
967
+ registerEndpoint(endpoint: NativeEndpoint): void;
968
+ /**
969
+ * A group link's `_tr` in its packet: what this side runs and how to dial it, once it runs a native endpoint there.
970
+ * Having said one, it goes on saying what it runs with no endpoint up too (`["webrtc/1"]`): the member's app keeps the
971
+ * last value it read and acts only on a packet that carries one, so a `_tr` that just stopped left it dialling a
972
+ * native transport nobody listens on, across restarts of both apps (an edge whose WebRTC failed once, node.ts
973
+ * `edgeWithoutRtc`, in the next run of the app). Never an empty list: an app with no WebRTC whose endpoint is not up
974
+ * yet says nothing, as before, and what it said in the run before holds.
975
+ */
976
+ private publishPacketTransports;
977
+ /** Counts the `_tr` values a signer was asked to sign (a device link): only the latest goes out. */
978
+ private transportsTurn;
979
+ /** The member's packet said which transports its app runs on this group link, and how to dial them. */
980
+ private peerPacketTransports;
981
+ /**
982
+ * The member's packet advertises and has carried no `_tr` for `TRANSPORTS_GONE_MS`: its app publishes none, which is
983
+ * what an app with WebRTC that runs no native endpoint on this link does. What an earlier packet said (kept by the
984
+ * owner across restarts) no longer holds: an app that said `["iroh/1"]` while its WebRTC failed and came back with
985
+ * WebRTC, from before it said so itself (`packetTransportsSaid`). Left as it was, this side ranked its transports
986
+ * against that list, found a native one nobody listens on or none at all, and never offered WebRTC again.
987
+ * Not on a device link: there only a signed value counts, and a missing one is signed by nobody.
988
+ */
989
+ private peerPacketTransportsGone;
990
+ /** A connection the contact dialled on one of this side's native endpoints. */
991
+ private takeDialIn;
992
+ /** A dial that came in while the contact's mailbox still said DHT-only, kept for the read that clears it (`BLOCKED_DIAL_WAIT_MS`). */
993
+ private blockedDial;
994
+ private parkBlockedDial;
995
+ private dropBlockedDial;
996
+ /**
997
+ * Back after a restart on a native transport: dialled at once, whichever side's turn it is. The contact likely still
998
+ * holds the old session and would notice only when its liveness gives up (a minute); a dial reaches it now and takes
999
+ * over (`attachReplacement`). Once only, and a knock that does not connect counts as no failure: the contact may
1000
+ * simply be away. Two dials crossing are settled by key order (see `registerEndpoint`).
1001
+ */
1002
+ private knock;
1003
+ canReleaseEndpoint(transport: PairedTransport): boolean;
1004
+ releaseEndpoint(transport: PairedTransport): Promise<void>;
1005
+ /** When the chat was last in use on its session: the contact's last frame of use, or the session's start. */
1006
+ get lastActivityAt(): number;
1007
+ /**
1008
+ * Whether the live session on this transport may end so another chat takes its listener (`yieldEndpoint`): open, and
1009
+ * unused, for `idleMs` at least (a session that just started has been in use for none of it); no call on, no file
1010
+ * moving, nothing being dialled or switched. `canReleaseEndpoint` never gives up a live session; this does, once idle.
1011
+ */
1012
+ canYieldEndpoint(transport: PairedTransport, idleMs: number): boolean;
1013
+ /**
1014
+ * Ends the idle live session on this transport and lets its listener go, for a chat in use that found every one
1015
+ * taken. The contact hears a goodbye, as when an app quits, rather than finding out when its pings go unanswered; the
1016
+ * record then lists the transport undescribed, so it stops dialling here. The chat goes on over the DHT (or WebRTC),
1017
+ * and takes a listener again the same way once it is in use. False when the session may not end (see above).
1018
+ */
1019
+ yieldEndpoint(transport: PairedTransport, idleMs: number): Promise<boolean>;
1020
+ private advertiseTransports;
1021
+ /**
1022
+ * `automatic`: this side stops choosing. Its policy still says `preferred` (the app's default) for the order
1023
+ * it dials in, but its switch intent drops to none, so the contact's explicit choice wins on the open session
1024
+ * and, without one, the current transport is kept. Never adds an unavailable adapter either way.
1025
+ */
1026
+ /**
1027
+ * `automatic`: back to the app's rule (no choice of this side's). `choice` false: the same transport with another
1028
+ * fallback (the Fallback switch), a policy change that raises no switch intent. A choice of the transport this side
1029
+ * already chose raises none either while that choice stands (see `TransportSwitch.chose`).
1030
+ */
1031
+ setTransportPreference(preferred: PairedTransport, fallback: boolean, automatic?: boolean, choice?: boolean): Promise<void>;
1032
+ private dial;
1033
+ private localDescriptors;
1034
+ /** True once attached (or when a newer attempt took over); the error otherwise. */
1035
+ private dialNative;
1036
+ /**
1037
+ * The native dial under way went to an endpoint the contact's newer packet no longer names for that transport: its
1038
+ * app started again (a page reloading, as both devices of a handoff do), and the endpoint dialled went with the old
1039
+ * one. That dial would end only at its connect timeout (Iroh: 20 s, then the next attempt's wait): it is let go, and
1040
+ * the endpoint the packet names dialled now. Not while a WebRTC offer of this attempt stands: the race that follows
1041
+ * it keeps its own order.
1042
+ */
1043
+ private redescribedDial;
1044
+ /** Whether this device has no network now (`GhostLinkOptions.offline`). */
1045
+ private isOffline;
1046
+ /**
1047
+ * The device's network came back. A native dial that started while it was away would end only at its connect timeout
1048
+ * (Iroh: 20 s), well past the return: it is let go, and the chat dialled again now. Its WebRTC offer, if one stands,
1049
+ * was made with no network too, and goes with it.
1050
+ */
1051
+ private networkBack;
1052
+ /** A WebRTC attempt this side dialled ended without opening: the next ranked transports, in order. */
1053
+ private dialAfterRtc;
1054
+ /**
1055
+ * WebRTC went first and its offer is out: if no answer came within `RACE_DIRECT_MS` (a direct transport ranked after
1056
+ * it) or `RACE_RELAYED_MS` (a relayed one), those are dialled too, the offer standing meanwhile.
1057
+ */
1058
+ private scheduleRace;
1059
+ /**
1060
+ * Back after an absence, this side answers an offer the contact made while it was away (it dials whatever its key):
1061
+ * the contact looks for that answer at the pace of an offer out a while (every 8 s on the relays), and its attempt may
1062
+ * end before it does. The direct transports both run are knocked on meanwhile, and the relayed ones where both apps
1063
+ * move off a relay once live (`upgrade/1`): the first live wins, and a knock that does not connect counts as nothing.
1064
+ */
1065
+ private maybeKnockAnswering;
1066
+ /** Back after an absence over WebRTC: not dialled yet, or this attempt's offer is the resume's (`offered.resume`). */
1067
+ private get resumingOverRtc();
1068
+ /** Both apps move a chat off a relay once live (`upgrade/1`): this one, and the contact's by its capability record. */
1069
+ private upgradesFromRelay;
1070
+ /** The contact's newest packet is older than `EXPECT_PEER_MS`: it is not signalling, and reads at a slow pace. */
1071
+ private contactQuiet;
1072
+ /** The direct transports of an attempt that resumes to a quiet contact, knocked on while its offer stands (`scheduleRace`). */
1073
+ private maybeKnockEarly;
1074
+ private knockEarly;
1075
+ /**
1076
+ * A native endpoint that started while this side's offer is out unanswered: its transport was not up when the dial
1077
+ * ranked what to try, and joins the race (and what the offer ending goes on to) if both sides allow it.
1078
+ */
1079
+ private joinRace;
1080
+ /** WebRTC could not start an attempt here: it goes last in the dial order for `RTC_UNSTARTED_MS`, while another transport remains. */
1081
+ private rtcUnstarted;
1082
+ /**
1083
+ * Whether this side dials although its key says it waits for the contact's offer: WebRTC cannot start here for now
1084
+ * (`rtcUnstarted`), so an offer of the contact's finds no answer, and this side has a native transport to dial, with
1085
+ * fallback allowed on both sides.
1086
+ */
1087
+ private dialsPastRtc;
1088
+ /**
1089
+ * A first pairing's inviter has no offer of the joiner's to wait for: WebRTC is missing here, or the joiner's record
1090
+ * says its app has none (a Linux Desktop's WebKitGTK), so its first packet carries none. A native transport the record
1091
+ * describes is dialled now. Waiting out `INVITER_DIAL_GRACE_MS` left two Linux Desktops 2.5 s more apart, and the
1092
+ * joiner, still reading, often went on without dialling for seconds (dht-direct on CI, 2026-10-07). Should the joiner
1093
+ * dial too, the two dials cross and the lower key's carries the chat (`parkCrossed`, `attachReplacement`).
1094
+ */
1095
+ private nothingToAwait;
1096
+ /** Whether a native dial of `transport` can go now: this side's endpoint is up and the contact's descriptor known. */
1097
+ private canDial;
1098
+ /**
1099
+ * Whether a dial has anything to try: WebRTC here (the contact's record, once read, listing it), or a native transport
1100
+ * both apps run with this side's endpoint up and the contact's descriptor read. A group link counts every dial: its
1101
+ * fast looks for the member's `_tr` end after a few (`PACKET_TRANSPORTS_FAST_ATTEMPTS`).
1102
+ */
1103
+ private anythingToDial;
1104
+ private clearRace;
1105
+ /**
1106
+ * The offer is still unanswered: the transports ranked after WebRTC that are due are dialled now, each once in this
1107
+ * attempt (the offer timing out goes on to those left, not to these again). A native session that goes live ends the
1108
+ * offer (`attach`); the offer answered first, the native dial is closed.
1109
+ */
1110
+ private race;
1111
+ /** A transport of the attempt under way did not connect. */
1112
+ private attemptFailed;
1113
+ /** The attempt under way ended without going live: kept as the last one, and told. `reason`: why, when nothing was tried. */
1114
+ private attemptEnded;
1115
+ /** The last attempt to go live that did not (WISP 100, "Why a chat is not live"); none while live. */
1116
+ get liveAttempt(): LiveAttempt | undefined;
1117
+ /**
1118
+ * Which side dials this chat to go live: the lower rendezvous key, or the joiner of a first pairing (WISP 100). The
1119
+ * other side answers, so what it can tell of a failed attempt is only what reached it.
1120
+ */
1121
+ get dialer(): "you" | "contact";
1122
+ /**
1123
+ * Chat goes over the data link when it is up, through Pkarr otherwise. A `preview` (WISP 401 § Link previews) goes
1124
+ * only with a paired message on the live session, and only while the frame stays within what a session takes;
1125
+ * the DHT has no room for one, and the text goes without it. A `reply` (WISP 401 § Replies) goes whole on the
1126
+ * session; on the DHT only its id does, which the contact looks up in its own history. `forwarded`: the hop count
1127
+ * of a forwarded message (WISP 401 § Forwards), on both paths (the DHT drops it when the packet has no room). `card`:
1128
+ * a status card (WISP 405 · Status Cards), on the live session only; on the DHT the text, its fallback, goes alone.
1129
+ */
1130
+ sendMessage(text: string, timestamp?: number, stableId?: string, preview?: LinkPreview, reply?: WireReply, forwarded?: number, card?: StatusCard): Promise<string | null>;
1131
+ /**
1132
+ * Says a file's offer on the DHT floor while the chat is not live (WISP 403 § Files), so the contact's chat shows its
1133
+ * bubble in its place; the bytes go once live. An error when it cannot go on the floor now: it waits for live then.
1134
+ */
1135
+ announceFile(file: DhtFileOffer, timestamp: number, reply?: WireReply, forwarded?: number): Promise<string | null>;
1136
+ /** Why a file's offer cannot go on the DHT floor now (`announceFile`), or null when it can. */
1137
+ fileAnnounceError(file: DhtFileOffer, timestamp: number, reply?: WireReply, forwarded?: number): string | null;
1138
+ /** What awaits its receipt on the DHT floor now, if anything does. */
1139
+ get dhtPendingId(): string | undefined;
1140
+ /** What went on the DHT floor under this id needs no more retries there (it went live, or was withdrawn). */
1141
+ settleDht(id: string): Promise<void>;
1142
+ /** Publishes a `_call` signal; a connected peer also gets it right away over the data link. */
1143
+ setCallSignal(signal: string | null): Promise<void>;
1144
+ /** Issues an HTTP request to a service the peer advertises. */
1145
+ request(serviceId: string, request: ClientRequest): Promise<ClientResponse>;
1146
+ /** Payments only travel over the data link: tokens and invoices do not fit in Pkarr, and should not sit there. */
1147
+ sendPaymentRequest(request: PaymentRequest): Promise<void>;
1148
+ /** Asks the contact for a way to pay it (an address, an invoice): its app answers with a request. */
1149
+ sendPaymentAsk(ask: PaymentAsk): Promise<void>;
1150
+ sendPayment(payment: Payment): Promise<void>;
1151
+ sendPaymentResult(result: PaymentResult): void;
1152
+ /** Sends a file over the data link, opening it first if needed. Files never travel through Pkarr. */
1153
+ sendFile(file: FileInfo, source: AsyncIterable<Uint8Array>): Promise<void>;
1154
+ /** Call after the set of shared services changed. */
1155
+ refreshServices(): Promise<void>;
1156
+ /**
1157
+ * Only the lower key offers, so two peers coming online together do not collide. A first pairing is
1158
+ * the exception: the joiner offers, whatever its key, in the very packet that says it is here (one hop
1159
+ * less than presence, then the inviter's offer), and the inviter waits for that offer. An inviter that
1160
+ * sees the joiner but no offer for `INVITER_DIAL_GRACE_MS` (an app from before this rule) offers itself,
1161
+ * and dials at once when no offer can come (`nothingToAwait`); the lower-key rule settles any collision, on both sides.
1162
+ */
1163
+ private maybeAutoConnect;
1164
+ /**
1165
+ * An automatic dial. One with nothing to try (`anythingToDial`) still says why (`liveAttempt`) and keeps the pace, but
1166
+ * is no failed attempt: the wait between attempts does not grow, and a first pairing does not turn `on-dht` for it.
1167
+ * Two Linux Desktops pairing over a slow DHT, neither having read the other's record yet, counted three such dials in
1168
+ * 12 s: the pairing turned `on-dht` and the next dial waited 160 s, though nothing had been tried.
1169
+ */
1170
+ private autoDial;
1171
+ /**
1172
+ * The contact answered this side's offer again, and the data link gave the attempt up (`DataLink.onAnswerReplaced`):
1173
+ * the contact is there, so this side dials again now. Its packet with that answer often has no room for its presence,
1174
+ * and waiting for a packet that says it is online left the edge to the next look at the background pace (60 s, CLI
1175
+ * bug hunt 2026-09-30).
1176
+ */
1177
+ private redial;
1178
+ /** WebRTC here refused a run of answers to this side's offers (`ANSWERS_REFUSED_PAUSES`): the next offer goes after a short pause. */
1179
+ private answersRefused;
1180
+ /**
1181
+ * A failed dial waits `dialWait` before the next, and only a look at the contact's record dials: the next one came at
1182
+ * the link's own pace (30 s in the background), which knows nothing of the backoff. A member let in to a group
1183
+ * reached one of its members 72 s after its welcome, 40 s of backoff and 32 s more for its next look (meshSignals on
1184
+ * CI, 2026-10-06). One look goes when the backoff ends (`liveAttempt.retryAt`), and its read decides, as any look's
1185
+ * does. A dial or a reset of the backoff since makes it moot: what comes next arms its own.
1186
+ */
1187
+ private lookAtRetry;
1188
+ /**
1189
+ * A packet of this link reached the relays after a dial whose offer never did (the relays failed, or their budget held
1190
+ * it, for the whole attempt): the contact saw nothing of that dial, so it is no reason to wait, and the next goes now.
1191
+ * Without this a dial made during an outage set the wait, three minutes once it had grown, from when the relays
1192
+ * answered again.
1193
+ */
1194
+ private dialSeenNow;
1195
+ /** How long after the last automatic dial the next one may go. A first pairing tries again sooner: the contact just read the invite and is waiting. */
1196
+ private dialWait;
1197
+ /** The name this side shows, told to a paired peer directly. */
1198
+ setNick(nick: string | undefined): void;
1199
+ /** The picture this side shows, told to a paired peer directly. Legacy chats have no room for it. */
1200
+ setAvatar(avatar: string | undefined): void;
1201
+ /** Older apps drop this frame (it carries no id). An empty `a` says the picture was removed. */
1202
+ private sendPairedAvatar;
1203
+ /** An empty `n` says there is no name to show (none set, removed, or not shared). */
1204
+ private sendPairedNick;
1205
+ private mergePresence;
1206
+ get peerProofAdapters(): ProofAdapter[];
1207
+ get peerProofSupport(): boolean;
1208
+ peerProofScope(): Promise<ProofScope>;
1209
+ get proofSession(): string | undefined;
1210
+ /**
1211
+ * The transcript hash of the session that is open and ready (WISP 401), lower-case hex, whatever proofs it offers:
1212
+ * what a device's enrollment (WISP 06) signs and derives its digits from. Undefined while no session is ready.
1213
+ */
1214
+ get sessionTranscriptHash(): string | undefined;
1215
+ /** Identity proofs can be exchanged now: both offers carry `identity-proof/1` and the channel is open. */
1216
+ get identitySupport(): boolean;
1217
+ /** This side's view of the authenticated channel, for identity presentations. */
1218
+ identityScope(): IdentityScope;
1219
+ sendIdentityProof(frame: object): void;
1220
+ sendPeerProof(frame: object): void;
1221
+ confirmPair(code: string): Promise<void>;
1222
+ get supportsFiles(): boolean;
1223
+ /** This device allows the way of paying in this chat. */
1224
+ paymentEnabled(method: PaymentMethodName): boolean;
1225
+ /** Both sides allow it. A chat from before pairing negotiates nothing: Cashu and Lightning as this device allows. */
1226
+ allowsPayment(method: PaymentMethodName): boolean;
1227
+ get supportsUsdtPayments(): boolean;
1228
+ get supportsArkPayments(): boolean;
1229
+ get supportsBarkPayments(): boolean;
1230
+ /** On-chain: only ever through the contact's `paired-payments` list (see PaymentMethodName). */
1231
+ get supportsBitcoinPayments(): boolean;
1232
+ /** Fedimint: only ever through the contact's `paired-payments` list, like on-chain. */
1233
+ get supportsFedimintPayments(): boolean;
1234
+ /** Spark: like on-chain, only ever through the contact's `paired-payments` list. */
1235
+ get supportsSparkPayments(): boolean;
1236
+ /** Payment messages flow at all: some way of paying is allowed by both sides. */
1237
+ get supportsPayments(): boolean;
1238
+ /** The contact accepts held items: its latest word on this session, else its handshake offer. */
1239
+ get peerAllowsHold(): boolean;
1240
+ /** Both sides offer `hold/1` on this session. */
1241
+ get supportsHold(): boolean;
1242
+ /** The contact's own choice about one way of paying, as it last said on this session or offered in the handshake. */
1243
+ peerAllowsPayment(method: PaymentMethodName): boolean;
1244
+ /**
1245
+ * The contact's choice about a way of paying in this chat, whether or not it has a wallet for it. Its session list
1246
+ * leaves out a way it has no wallet of (its networks name none): that one is as its handshake offer said. What is
1247
+ * remembered for a later request, which goes when the chat is live: a wallet made meanwhile then counts.
1248
+ */
1249
+ peerChoosesPayment(method: PaymentMethodName): boolean;
1250
+ /** Takes effect at once; a connected contact is told on the open session, and the next handshake offers it. */
1251
+ setHoldSupport(on: boolean, top?: number): void;
1252
+ /** Older apps drop this frame (it carries no id) and keep using the handshake offer. */
1253
+ private sendHoldState;
1254
+ /** Takes effect at once, and a connected contact is told on the open session; the next handshake offers it too. */
1255
+ setPaymentMethods(methods: Partial<Record<PaymentMethodName, boolean>>): void;
1256
+ /** This side's wallets changed (one was created): a connected contact is told at once. */
1257
+ setPaymentNetworks(networks: PaymentNetworks): void;
1258
+ /**
1259
+ * The networks the contact has a wallet on for this way of paying, as it said on this session. Undefined: it did
1260
+ * not say (an older app, or before its first word): any network may meet.
1261
+ */
1262
+ peerPaymentNetworks(method: PaymentMethodName): ("mainnet" | "testnet")[] | undefined;
1263
+ /** The whole map as the contact said it: a way of paying it has no wallet of is not in it. Undefined: it did not say. */
1264
+ peerWalletNetworks(): PaymentNetworks | undefined;
1265
+ /** The apps this contact may reach, said on the open session. Older apps drop the frame (no id). */
1266
+ private sendPairedServices;
1267
+ private offeredCapabilities;
1268
+ /** Both ends announced this device capability on the open session (a device link only). */
1269
+ supportsDevice(capability: DeviceCapability): boolean;
1270
+ /** A frame to the person's other device. Only while both ends announced the capability its type travels under; never queued. */
1271
+ sendDeviceFrame(frame: DeviceFrame): void;
1272
+ /** Both sides offer `calls/1` on the open session: call signals can flow. Calls need a live session. */
1273
+ get supportsCalls(): boolean;
1274
+ /** Both sides offer `services/1` on the open session: shared web apps can be listed and reached. */
1275
+ get supportsServices(): boolean;
1276
+ /** Both sides offer `files/3` on the open session: files of any size, offered and resumed. */
1277
+ get supportsLargeFiles(): boolean;
1278
+ /** Both sides offer `typing/1` on the open session: typing can be said and shown. */
1279
+ get supportsTyping(): boolean;
1280
+ /** Both sides offer `react/1` on the open session: reactions can be said and confirmed here. */
1281
+ get supportsReactions(): boolean;
1282
+ /**
1283
+ * Says a reaction of this side (WISP 401 § Reactions) on the live session, once both sides offer `react/1`. An
1284
+ * error when it could not go now: the caller keeps it, and it goes again later (or on the DHT).
1285
+ */
1286
+ /**
1287
+ * This side has reactions the contact has not confirmed (`reactions` in the DHT options): off the live session they
1288
+ * ride on the DHT envelopes, and one goes now (WISP 403 § Reactions).
1289
+ */
1290
+ reactionsPending(): void;
1291
+ sendReaction(reaction: WireReaction): string | null;
1292
+ /** The contact is typing now, as it said on this session. */
1293
+ get peerTyping(): boolean;
1294
+ /** What the contact is doing now (typing, recording, thinking, and a bot's status), or null. */
1295
+ get peerTypingActivity(): TypingActivity | null;
1296
+ /** Both sides offer `wake/1` on the open session: push subscriptions can be shared (WISP 401 § Wake-up push). */
1297
+ get supportsWake(): boolean;
1298
+ /**
1299
+ * Shares how to wake this side's closed web app (null: stop, forget it) on the live session, once both sides offer
1300
+ * `wake/1`. False when it could not go now: the caller shares it again on the next session.
1301
+ */
1302
+ sendWake(target: WakeTarget | null): boolean;
1303
+ /** Both sides offer `pin/1` on the open session: a pin can be said and confirmed. */
1304
+ get supportsPins(): boolean;
1305
+ /**
1306
+ * Says this side's pin (WISP 401 § Pinned message) on the live session, once both sides offer `pin/1`. An error when
1307
+ * it could not go now: the caller keeps it, and it goes on the next session.
1308
+ */
1309
+ sendPin(pin: WirePin): string | null;
1310
+ /** Both sides offer `edit/1` on the open session: edits can be said and confirmed. */
1311
+ get supportsEdits(): boolean;
1312
+ /** Both sides offer `status-card/1` on the open session: the contact shows cards and takes a card's edits past 100. */
1313
+ get supportsStatusCards(): boolean;
1314
+ /**
1315
+ * Says an edit of one of this side's messages (WISP 401 § Edits): on the live session once both sides offer `edit/1`;
1316
+ * while not live, on the DHT floor when `dht` says the contact's app takes edits there (WISP 403 § Edits). An error
1317
+ * when it could not go now; the caller keeps it and says it again later.
1318
+ */
1319
+ sendEdit(edit: WireEdit, { dht }?: {
1320
+ dht?: boolean;
1321
+ }): Promise<string | null>;
1322
+ /** Confirms an edit of the contact's that waited for its message (`onMessageEdit` returned false). */
1323
+ confirmEdit(id: string, e: number): void;
1324
+ /**
1325
+ * This side is typing (true) or stopped (false). Said only on the live session and only when both sides offer
1326
+ * `typing/1`; never on the DHT. A `start` goes at most every few seconds (at once when `activity` changes), a
1327
+ * `stop` only after a `start`.
1328
+ */
1329
+ setTyping(typing: boolean, activity?: TypingActivity): void;
1330
+ private resumeTyping;
1331
+ /** Both sides offer `apps/1` on the open session: mini-apps can talk (WISP 1200 § In a chat). */
1332
+ get supportsApps(): boolean;
1333
+ /** The apps the contact has open on this session (chat app id to version). */
1334
+ get peerApps(): ReadonlyMap<string, string>;
1335
+ /**
1336
+ * This side opened an app in this chat (or updated it): `open` goes now when both sides offer `apps/1` on the live
1337
+ * session, and again on every session that comes back while the app stays open. Never on the DHT.
1338
+ */
1339
+ openApp(app: string, version: string): void;
1340
+ /** This side closed an app in this chat: `close` goes now when it can; nothing is said later. */
1341
+ closeApp(app: string): void;
1342
+ /**
1343
+ * One data frame of an app open on both sides, on the live session only. An error when it did not go: nothing is
1344
+ * kept to send later.
1345
+ */
1346
+ sendAppData(app: string, data: unknown): AppSendError | null;
1347
+ /** What the contact had open is gone (`apps/1` is no longer agreed, or this link stopped): each app hears it now. */
1348
+ private appsEnded;
1349
+ private appsGrace;
1350
+ /**
1351
+ * The session ended or a new one took its place (a transport switch, a resume, a re-dial): what the contact had open
1352
+ * is held for `APP_RESUME_GRACE_MS` (WISP 1200 § In a chat). The next session's `open` takes each back, and the app
1353
+ * hears only that open, not a close first; one not said again by then is closed with `offline`.
1354
+ */
1355
+ private appsSuspended;
1356
+ /** Whether files/3 was agreed on the session open now; kept to say when that changes. */
1357
+ private filesOpen;
1358
+ private emitFilesSession;
1359
+ /** A files/3 frame to the contact, on the open session. False when files/3 cannot flow now. */
1360
+ sendFilesFrame(frame: Record<string, unknown>): boolean;
1361
+ /**
1362
+ * Resolves once the open session can take another files/3 data frame; undefined when it can now. A channel with a send budget (native and
1363
+ * iroh ones throw past 120 KiB) gives files a quarter of it, so a ping, a message or any other frame still fits
1364
+ * while a file goes; others keep under the high water mark, as files/2 does.
1365
+ */
1366
+ filesWritable(): Promise<void> | undefined;
1367
+ /** What each side offers on the open session, for showing why something is unavailable. `peer` is null until it says. */
1368
+ get sessionOffers(): {
1369
+ mine: SessionCapability[];
1370
+ peer: string[] | null;
1371
+ };
1372
+ /** Why a call cannot be placed in this paired chat right now, or null when it can. */
1373
+ get callsUnavailable(): string | null;
1374
+ /** Says what this side offers on the open session. Older apps drop the frame (no id). */
1375
+ private sendSessionCapabilities;
1376
+ /** The contact said what it offers: start what both sides now agree on. */
1377
+ private sessionCapabilitiesChanged;
1378
+ /** Both sides announced groups on this session and it is open. */
1379
+ get groupsSupport(): boolean;
1380
+ /** Both sides announced this version of groups (1: `group-mesh/1`, 2: `group-community/1` too). */
1381
+ supportsGroupVersion(version: number): boolean;
1382
+ /** A `group-*` frame to the peer. Only while both sides support groups; never queued. */
1383
+ sendGroupFrame(frame: object): void;
1384
+ /** Older apps drop this frame (it carries no id): to them this contact has no groups. */
1385
+ private sendGroupsSupport;
1386
+ /** Older apps drop this frame (it carries no id) and keep using the handshake offer. */
1387
+ private sendPaymentMethods;
1388
+ /**
1389
+ * The contact said goodbye on the last live session (its app quit or stopped) and has published nothing since but its
1390
+ * leave packet: its app is not running, so a dial now waits for nobody until it gives up.
1391
+ */
1392
+ get contactAway(): boolean;
1393
+ requirePaymentSupport(): Promise<void>;
1394
+ private requireLegacyCapabilities;
1395
+ private cancelCandidate;
1396
+ private prepareSwitch;
1397
+ private attachCandidate;
1398
+ /**
1399
+ * Both sides dialled at once (two apps back after a restart, each knocking): the lower key's dial carries the chat, on
1400
+ * both sides; the higher key's side takes it over as a replacement (`attachReplacement`). Here, on the lower key's
1401
+ * side, the contact's connection waits: dropped once this side's own dial connects, taken if that dial fails, or has
1402
+ * not connected within `CROSSED_WAIT_MS` (the contact may be dialling an app that is not up yet, for as long as its
1403
+ * dial takes to give up).
1404
+ */
1405
+ private crossed;
1406
+ private parkCrossed;
1407
+ private dropCrossed;
1408
+ /** This side's dial ended: a connection of the contact's that waited is dropped, or, if nothing connected, taken now. */
1409
+ private settleCrossed;
1410
+ /**
1411
+ * The pinned contact dialled in while this side still holds a session with it. A contact dials only with no session
1412
+ * of its own (a switch both agreed goes through `attachCandidate`): its app restarted, or lost the session, and the
1413
+ * one held here is dead without this side having heard (a crash, a quit that said nothing, a network change). The new
1414
+ * connection authenticates first, then takes over; a dial that does not authenticate closes and changes nothing.
1415
+ * Before the pin a held session keeps the chat, as it always did.
1416
+ */
1417
+ private attachReplacement;
1418
+ /**
1419
+ * Connections that came in on this side's native endpoints. Their address was in the capability record, which before
1420
+ * the pin anyone holding a copy of the invite could read: a key other than the pinned one on such a connection proves
1421
+ * no more than on the DHT, so it closes that connection and nothing else.
1422
+ */
1423
+ private readonly dialedIn;
1424
+ /** Connections whose session started with no key pinned nor named by the invite. */
1425
+ private readonly openedUnpinned;
1426
+ /**
1427
+ * `migration`: the channel is a candidate that takes over from the session open now once it authenticated. With a
1428
+ * `plan`, a live switch both sides agreed; without one, a replacement (`attachReplacement`): the contact dialled
1429
+ * afresh, having no session with this side any more.
1430
+ */
1431
+ private attach;
1432
+ /**
1433
+ * Pings the paired peer; a session that stopped answering is closed, so it can be dialled again. A peer
1434
+ * that said in its offer that it answers pings counts from the open; any other counts once it answered
1435
+ * one (an app that never does is never cut off for it).
1436
+ */
1437
+ private startLiveness;
1438
+ private stopLiveness;
1439
+ /** `live`: a liveness ping, whose pong measures the round trip. */
1440
+ private sendPing;
1441
+ /**
1442
+ * Resolves once the contact's app handled every frame sent on this session so far: it answers a ping in the order
1443
+ * frames come (every app since 1.0), so the pong to one sent now says so, however slowly it handles them. A group
1444
+ * member's catch-up answer goes a slice at a time on it (`GroupSessionHooks.handled`). `false` when it cannot tell:
1445
+ * no session, or a contact that answers no ping. `"late"` with no answer within `HANDLED_WAIT_MS`: a contact that
1446
+ * answers pings is still handling what came before (a phone with a long history), not one that cannot say.
1447
+ */
1448
+ handled(): Promise<boolean | "late">;
1449
+ /** Something came back on the session: the ping's wait is over. */
1450
+ private heardFromPeer;
1451
+ /**
1452
+ * The session runs on a native transport, its last ping went unanswered, and the contact's newer packet names another
1453
+ * endpoint for that transport: the contact's app started again (a web page reloading, as a device that takes the
1454
+ * profile does twice), and the endpoint this session runs on went with it, with nothing said. A browser's relay-only
1455
+ * Iroh closes nothing as a page goes, and QUIC notices only at its idle timeout (30 s): until then this side held a
1456
+ * session nothing answered, and the contact, whose key does not dial, waited for it to dial (a Use here said hello
1457
+ * into that session and gave up "unreachable", Omarchy 2026-10-05). The session is let go, and the new endpoint
1458
+ * dialled now, as when the session closes.
1459
+ */
1460
+ private restartedRedial;
1461
+ private dropDeadSession;
1462
+ /**
1463
+ * A live session ended without this side ending it (its channel closed, or its liveness gave up): tried again at
1464
+ * once, and the contact is watched closely for a while, since an app that went away is usually back in seconds.
1465
+ */
1466
+ private peerLost;
1467
+ /**
1468
+ * The contact said goodbye on the live session: its app is closing (and, often, starting again). The session ends now
1469
+ * rather than when liveness gives up, and the contact is watched closely: the side that dials does so once a newer
1470
+ * packet shows it back, the other looks fast for its dial or offer.
1471
+ */
1472
+ private peerDeparted;
1473
+ /**
1474
+ * A packet of the contact's not seen before, fresh, while nothing is live, soon after a live session ended: it is back
1475
+ * (its app restarted), so the wait that the attempts since built up is over, and the next dial goes now. Once per
1476
+ * loss: a contact that is there but unreachable publishes often, and the wait between attempts is what spares the
1477
+ * relays then.
1478
+ */
1479
+ private peerPacketArrived;
1480
+ /**
1481
+ * This app is going away (it quits, the page closes): the contact hears it on the live session now, rather than when
1482
+ * its liveness gives up about a minute later, and watches for this app to come back. Older apps drop the frame (it
1483
+ * carries no id). Synchronous, so it goes before anything else an app does on its way out.
1484
+ */
1485
+ depart(): void;
1486
+ /** A link made just now for a peer that is about to show up (a group's entry session): look fast for a while. */
1487
+ expectPeer(): void;
1488
+ /** The peer's packet is at hand without a relay (a member of the group carried it, `CarriedTransport`): read it now. */
1489
+ look(): void;
1490
+ /**
1491
+ * Someone is here again (the chat was opened, the window came back): look now, and try at once rather
1492
+ * than after the wait between failed attempts. `network`: the device's network just came back.
1493
+ */
1494
+ wake(params?: {
1495
+ network?: boolean;
1496
+ }): void;
1497
+ /**
1498
+ * Back in front with no session, after one was live: the contact likely did not notice this app go (a phone puts a
1499
+ * backgrounded app to sleep without a word), and reads this chat at its slow pace (30 s on the relays in the
1500
+ * background), so an offer or a fresh packet of this side's waited about that long for it. The chat resumes as after a
1501
+ * restart (WISP 100, "Back after a restart"): this side dials whatever its key, on the transport it was live on, and
1502
+ * knocks on the contact's other transports as its offer goes out, which reaches the contact at once.
1503
+ */
1504
+ private resumeAfterAbsence;
1505
+ /** A ping on the session right after a wake, with `PONG_WAIT_MS` for its answer: none, and the session is dead. */
1506
+ private probeAfterWake;
1507
+ private detach;
1508
+ private rejectWaiters;
1509
+ private handleFrame;
1510
+ }