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