@ghostlytools/sdk 0.0.0-stage → 1.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (145) hide show
  1. package/README.md +13 -2
  2. package/dist/app.js +67 -0
  3. package/dist/app.js.map +1 -0
  4. package/dist/core.js +207 -0
  5. package/dist/core.js.map +1 -0
  6. package/dist/fakes-CBIuqo5e.js +536 -0
  7. package/dist/fakes-CBIuqo5e.js.map +1 -0
  8. package/dist/fakes.js +2 -0
  9. package/dist/index.js +179 -0
  10. package/dist/index.js.map +1 -0
  11. package/dist/keet-identity-key-BylxCPl4.js +76483 -0
  12. package/dist/keet-identity-key-BylxCPl4.js.map +1 -0
  13. package/dist/src-DCeLPsi-.js +31056 -0
  14. package/dist/src-DCeLPsi-.js.map +1 -0
  15. package/dist/testing.js +330 -0
  16. package/dist/testing.js.map +1 -0
  17. package/dist/types/browser/src/engine/paymentAdapters/providers/contractSuite.d.ts +41 -0
  18. package/dist/types/browser/src/engine/paymentAdapters/providers/lightning.d.ts +103 -0
  19. package/dist/types/browser/src/engine/paymentAdapters/providers/onchain.d.ts +88 -0
  20. package/dist/types/browser/src/engine/paymentAdapters/providers/testing.d.ts +89 -0
  21. package/dist/types/browser/src/engine/paymentAdapters/providers/types.d.ts +151 -0
  22. package/dist/types/browser/src/plugins/bundled.d.ts +8 -0
  23. package/dist/types/browser/src/plugins/registry.d.ts +57 -0
  24. package/dist/types/browser/src/proofs/contract.d.ts +262 -0
  25. package/dist/types/browser/src/proofs/contractSuite.d.ts +27 -0
  26. package/dist/types/browser/src/proofs/testing.d.ts +36 -0
  27. package/dist/types/browser/src/proofs/verify.d.ts +23 -0
  28. package/dist/types/browser/src/shared/mints.d.ts +50 -0
  29. package/dist/types/core/src/appBundle.d.ts +173 -0
  30. package/dist/types/core/src/appStatements.d.ts +142 -0
  31. package/dist/types/core/src/appStore.d.ts +133 -0
  32. package/dist/types/core/src/appUpdates.d.ts +88 -0
  33. package/dist/types/core/src/atprotoIdentity.d.ts +49 -0
  34. package/dist/types/core/src/atprotoRepo.d.ts +101 -0
  35. package/dist/types/core/src/avatar.d.ts +19 -0
  36. package/dist/types/core/src/bip322.d.ts +57 -0
  37. package/dist/types/core/src/bitcoinAddress.d.ts +5 -0
  38. package/dist/types/core/src/bitcoinMessage.d.ts +15 -0
  39. package/dist/types/core/src/bitcoinScript.d.ts +69 -0
  40. package/dist/types/core/src/bolt11.d.ts +30 -0
  41. package/dist/types/core/src/bytes.d.ts +11 -0
  42. package/dist/types/core/src/callSignal.d.ts +232 -0
  43. package/dist/types/core/src/canonicalJson.d.ts +22 -0
  44. package/dist/types/core/src/capsRecord.d.ts +234 -0
  45. package/dist/types/core/src/catchUp.d.ts +45 -0
  46. package/dist/types/core/src/chatFiles.d.ts +271 -0
  47. package/dist/types/core/src/clockWatch.d.ts +72 -0
  48. package/dist/types/core/src/communityRendezvous.d.ts +113 -0
  49. package/dist/types/core/src/crypto.d.ts +10 -0
  50. package/dist/types/core/src/datalink.d.ts +187 -0
  51. package/dist/types/core/src/deviceInvite.d.ts +51 -0
  52. package/dist/types/core/src/deviceLink.d.ts +70 -0
  53. package/dist/types/core/src/dhtDelivery.d.ts +403 -0
  54. package/dist/types/core/src/dhtFiles.d.ts +46 -0
  55. package/dist/types/core/src/did.d.ts +134 -0
  56. package/dist/types/core/src/didDht.d.ts +155 -0
  57. package/dist/types/core/src/directPath.d.ts +63 -0
  58. package/dist/types/core/src/dns.d.ts +41 -0
  59. package/dist/types/core/src/domainProofs.d.ts +88 -0
  60. package/dist/types/core/src/engineErrors.d.ts +90 -0
  61. package/dist/types/core/src/enroll.d.ts +98 -0
  62. package/dist/types/core/src/files.d.ts +73 -0
  63. package/dist/types/core/src/forwards.d.ts +12 -0
  64. package/dist/types/core/src/frames.d.ts +211 -0
  65. package/dist/types/core/src/ghostlink.d.ts +1510 -0
  66. package/dist/types/core/src/groupCommits.d.ts +103 -0
  67. package/dist/types/core/src/groupCommunity.d.ts +714 -0
  68. package/dist/types/core/src/groupCrypto.d.ts +60 -0
  69. package/dist/types/core/src/groupEdits.d.ts +67 -0
  70. package/dist/types/core/src/groupEntry.d.ts +61 -0
  71. package/dist/types/core/src/groupFiles.d.ts +106 -0
  72. package/dist/types/core/src/groupHubs.d.ts +61 -0
  73. package/dist/types/core/src/groupMentions.d.ts +27 -0
  74. package/dist/types/core/src/groupMeta.d.ts +162 -0
  75. package/dist/types/core/src/groupSession.d.ts +710 -0
  76. package/dist/types/core/src/groupSignals.d.ts +167 -0
  77. package/dist/types/core/src/groupTyping.d.ts +56 -0
  78. package/dist/types/core/src/groupWake.d.ts +68 -0
  79. package/dist/types/core/src/handoff.d.ts +255 -0
  80. package/dist/types/core/src/http.d.ts +125 -0
  81. package/dist/types/core/src/identity.d.ts +17 -0
  82. package/dist/types/core/src/identityProofs.d.ts +243 -0
  83. package/dist/types/core/src/identityTimeline.d.ts +72 -0
  84. package/dist/types/core/src/image.d.ts +33 -0
  85. package/dist/types/core/src/index.d.ts +100 -0
  86. package/dist/types/core/src/invite.d.ts +128 -0
  87. package/dist/types/core/src/link.d.ts +353 -0
  88. package/dist/types/core/src/linkPreview.d.ts +60 -0
  89. package/dist/types/core/src/linkTrace.d.ts +12 -0
  90. package/dist/types/core/src/lnurl.d.ts +99 -0
  91. package/dist/types/core/src/messageTime.d.ts +28 -0
  92. package/dist/types/core/src/miniApp.d.ts +141 -0
  93. package/dist/types/core/src/pairedApps.d.ts +151 -0
  94. package/dist/types/core/src/pairedCalls.d.ts +59 -0
  95. package/dist/types/core/src/pairedCapabilities.d.ts +101 -0
  96. package/dist/types/core/src/pairedEdits.d.ts +83 -0
  97. package/dist/types/core/src/pairedFiles.d.ts +30 -0
  98. package/dist/types/core/src/pairedHttp.d.ts +15 -0
  99. package/dist/types/core/src/pairedSession.d.ts +163 -0
  100. package/dist/types/core/src/pairedSignal.d.ts +17 -0
  101. package/dist/types/core/src/pairedTransports.d.ts +76 -0
  102. package/dist/types/core/src/pairedTyping.d.ts +130 -0
  103. package/dist/types/core/src/pairedWake.d.ts +109 -0
  104. package/dist/types/core/src/pairingProgress.d.ts +107 -0
  105. package/dist/types/core/src/paymentIntent.d.ts +111 -0
  106. package/dist/types/core/src/paymentUri.d.ts +34 -0
  107. package/dist/types/core/src/payments.d.ts +97 -0
  108. package/dist/types/core/src/peerProofs.d.ts +98 -0
  109. package/dist/types/core/src/pins.d.ts +73 -0
  110. package/dist/types/core/src/pkarr.d.ts +48 -0
  111. package/dist/types/core/src/pkdns.d.ts +35 -0
  112. package/dist/types/core/src/pubkyProofs.d.ts +25 -0
  113. package/dist/types/core/src/pubkyRing.d.ts +21 -0
  114. package/dist/types/core/src/reactions.d.ts +108 -0
  115. package/dist/types/core/src/records.d.ts +89 -0
  116. package/dist/types/core/src/relay.d.ts +437 -0
  117. package/dist/types/core/src/relayBreaker.d.ts +99 -0
  118. package/dist/types/core/src/replies.d.ts +41 -0
  119. package/dist/types/core/src/services.d.ts +35 -0
  120. package/dist/types/core/src/setUpdate.d.ts +53 -0
  121. package/dist/types/core/src/signal.d.ts +53 -0
  122. package/dist/types/core/src/signer.d.ts +13 -0
  123. package/dist/types/core/src/sparkAddress.d.ts +37 -0
  124. package/dist/types/core/src/sshsig.d.ts +74 -0
  125. package/dist/types/core/src/statusCards.d.ts +253 -0
  126. package/dist/types/core/src/storeForward.d.ts +144 -0
  127. package/dist/types/core/src/text.d.ts +20 -0
  128. package/dist/types/core/src/transport.d.ts +151 -0
  129. package/dist/types/core/src/transportSwitch.d.ts +160 -0
  130. package/dist/types/core/src/turnRead.d.ts +145 -0
  131. package/dist/types/core/src/turnRecord.d.ts +165 -0
  132. package/dist/types/core/src/version.d.ts +9 -0
  133. package/dist/types/core/src/video.d.ts +44 -0
  134. package/dist/types/core/src/voice.d.ts +88 -0
  135. package/dist/types/core/src/webPush.d.ts +58 -0
  136. package/dist/types/sdk/src/app.d.ts +23 -0
  137. package/dist/types/sdk/src/core.d.ts +7 -0
  138. package/dist/types/sdk/src/fakes.d.ts +6 -0
  139. package/dist/types/sdk/src/index.d.ts +26 -0
  140. package/dist/types/sdk/src/testing.d.ts +7 -0
  141. package/dist/types-DvtCy3WB.js +99 -0
  142. package/dist/types-DvtCy3WB.js.map +1 -0
  143. package/dist/verify-DBGw6wYt.js +106 -0
  144. package/dist/verify-DBGw6wYt.js.map +1 -0
  145. package/package.json +70 -4
@@ -0,0 +1,128 @@
1
+ /**
2
+ * A link between two peers: my identity, the peer's public key and the shared
3
+ * secretbox key. The slash forms are the invite formats of Ghostly 0.4
4
+ * (`<seed>/<peer public key>/<encryption key>`) and of pre-0.5 builds
5
+ * (`pair1/…`, `pair2d/…`); a current app reads them and makes only `ghostly1…`
6
+ * codes (WISP 801).
7
+ */
8
+ export interface LinkParams {
9
+ profile?: "paired-chat/1";
10
+ deliveryMode?: "stream" | "dht";
11
+ seedB64: string;
12
+ peerPubKeyZ32: string;
13
+ encKeyB64: string;
14
+ /**
15
+ * The inviter's participation public key, carried by a `ghostly1` code: the
16
+ * joiner pins the inviter from it before either path answers.
17
+ */
18
+ peerParticipationKeyZ32?: string;
19
+ /**
20
+ * The inviter's own participation seed, on the inviter's side only (the one
21
+ * whose public key its invite carries). Never part of a code.
22
+ */
23
+ participationSeedB64?: string;
24
+ }
25
+ /** The human-readable part of every invite code: codes read `ghostly1…`. */
26
+ export declare const INVITE_HRP = "ghostly";
27
+ /** The format version this build makes; the first data symbol (`p`). */
28
+ export declare const INVITE_VERSION = 1;
29
+ /**
30
+ * The version of a code that adds a device to a profile (WISP 06 § Adding a device, `deviceInvite.ts`): no chat. The
31
+ * chat reader refuses it as `device`; an app from before WISP 06 refuses it as a newer version.
32
+ */
33
+ export declare const DEVICE_INVITE_VERSION = 2;
34
+ /** Decoders refuse anything longer before computing a checksum (WISP 801 lifts bech32's 90). */
35
+ export declare const INVITE_MAX_LENGTH = 1023;
36
+ /** The canonical link host (Q11): the code travels in the fragment, never sent to a server. */
37
+ export declare const INVITE_LINK_ORIGIN = "https://ghostly.tools";
38
+ /**
39
+ * Why a code was refused, each with the one message the UI shows for it. `device`: a code that adds a device to a
40
+ * profile (WISP 06), which no chat can be made from.
41
+ */
42
+ export type InviteRefusal = "typo" | "update" | "not-ghostly" | "damaged" | "device";
43
+ /** What reading a pasted or scanned invite gives: the chat's parameters, or why not. */
44
+ export type InviteReading = {
45
+ ok: true;
46
+ params: LinkParams;
47
+ format: "ghostly1" | "pair1" | "pair2d" | "legacy";
48
+ } | {
49
+ ok: false;
50
+ reason: InviteRefusal;
51
+ detail?: string;
52
+ };
53
+ /** The `ghostly1…` code of a new chat. `params` must carry the inviter's participation key. */
54
+ export declare function encodeGhostlyInvite(params: LinkParams): string;
55
+ /**
56
+ * The code for these parameters: `ghostly1…` when they carry the inviter's
57
+ * participation key (every invite a current app makes), else the slash form
58
+ * they were read from, so a stored older code round-trips.
59
+ */
60
+ export declare function encodeInviteCode(params: LinkParams): string;
61
+ /** `https://ghostly.tools/#ghostly1…`: the form an invite is shared in. */
62
+ export declare function inviteLink(code: string, origin?: string): string;
63
+ /** What goes in a QR code: upper case, so the code fits the alphanumeric mode. Older codes stay as they are. */
64
+ export declare function inviteQrText(code: string): string;
65
+ /**
66
+ * The QR segments of an invite's link, in capitals: `HTTPS://GHOSTLY.TOOLS/`
67
+ * and the code in alphanumeric mode, the `#` between them in byte mode (QR
68
+ * version 9 at level M). An encoder that takes a list of strings picks each
69
+ * one's mode; one string with the `#` in it would be all bytes. Older codes
70
+ * stay one segment, as they are.
71
+ */
72
+ export declare function inviteQrSegments(code: string, origin?: string): string[];
73
+ /**
74
+ * Reads an invite by the rules of WISP 801: a `ghostly1…` code in any case, bare
75
+ * or in a link (`https://ghostly.tools/#…`, `app.ghostly.tools/#…`), or one of
76
+ * the older slash forms. A refused code is never retried as another format.
77
+ */
78
+ export declare function readInviteCode(input: string): InviteReading;
79
+ /** The parameters of an invite, or null when it is refused (`readInviteCode` says why). */
80
+ export declare function decodeInviteCode(input: string): LinkParams | null;
81
+ /** Creates both ends of a link: keep `mine`, hand `invite` to the peer. */
82
+ export declare function createLink(): {
83
+ mine: LinkParams;
84
+ invite: LinkParams;
85
+ };
86
+ /**
87
+ * A new chat, the way a current app makes one: `mine` keeps this side's
88
+ * participation seed, `invite` carries its public key, and `inviteCode` is the
89
+ * `ghostly1…` code to hand over.
90
+ */
91
+ export declare function createChatInvite(): {
92
+ mine: LinkParams;
93
+ invite: LinkParams;
94
+ inviteCode: string;
95
+ };
96
+ /** A chat this side already has, as `inviteOwnership` reads it: its own seed and the contact's link key. */
97
+ export interface KnownLink {
98
+ seedB64: string;
99
+ peerPubKeyZ32: string;
100
+ }
101
+ /**
102
+ * Whose invite a code is, among the chats a profile already has: `own` when this profile made it (the
103
+ * invite's seed derives the contact key one of its chats waits for, which holds for every format, since
104
+ * an inviter keeps the contact's public key), `joined` when this profile already joined by it (the
105
+ * invite's seed is a chat's own), `new` otherwise. Another profile's chats are never passed, so its
106
+ * invites read as new: two profiles on one app may chat with each other.
107
+ */
108
+ export type InviteOwnership<T extends KnownLink> = {
109
+ kind: "own" | "joined";
110
+ link: T;
111
+ } | {
112
+ kind: "new";
113
+ };
114
+ export declare function inviteOwnership<T extends KnownLink>(invite: Pick<LinkParams, "seedB64">, links: Iterable<T>): InviteOwnership<T>;
115
+ /**
116
+ * A join refused because the invite is this profile's own (WISP 801 Q9). The message carries the reason
117
+ * and the chat that owns the invite, so a client on the other side of an RPC (which gets the message and
118
+ * nothing else) reads them back with `ownInviteRefusal`.
119
+ */
120
+ export declare class OwnInviteError extends Error {
121
+ readonly linkId: string | null;
122
+ readonly reason = "own-invite";
123
+ constructor(linkId: string | null);
124
+ }
125
+ /** The refusal an error (or an error's message, as an RPC hands it over) carries, or null when it is another error. */
126
+ export declare function ownInviteRefusal(error: unknown): {
127
+ linkId: string | null;
128
+ } | null;
@@ -0,0 +1,353 @@
1
+ import { type Identity } from "./identity.js";
2
+ import type { LinkParams } from "./invite.js";
3
+ import { type CompactMessage, type ResolvedLink, type ResolvedMessage } from "./records.js";
4
+ import type { ServiceAd } from "./services.js";
5
+ import type { SignalSight } from "./signal.js";
6
+ import { type PkarrTransport } from "./transport.js";
7
+ /**
8
+ * The Pkarr side of a link: publish my records, poll the peer's. This is the
9
+ * loop Ghostly Desktop runs in `useChat`, without React, so every client can
10
+ * share it.
11
+ */
12
+ export interface PollIntervals {
13
+ /** The user is looking at the link. */
14
+ active: number;
15
+ /** …but nothing happened for a minute. */
16
+ idle: number;
17
+ /** Signaling in progress. */
18
+ fast: number;
19
+ /** Nobody is looking. */
20
+ background: number;
21
+ /** The data link is up and carries everything; Pkarr only has to notice re-offers. */
22
+ connected: number;
23
+ }
24
+ /** What Ghostly Desktop uses against the DHT. */
25
+ export declare const DHT_POLL_INTERVALS: PollIntervals;
26
+ /** Relays rate limit by IP, and several peers may sit behind one address. */
27
+ export declare const RELAY_POLL_INTERVALS: PollIntervals;
28
+ /**
29
+ * An offer to a saved contact (a chat, a group's edge) is looked at fast for an answer this long after it went out,
30
+ * then less often (`OFFER_STEP_MAX`) for the rest of its window. A contact that is there answers within seconds;
31
+ * one that still holds the session this app had before it restarted answers only once that session goes (about 20 s
32
+ * with node-datachannel, 45 s where liveness finds out). An app back with several chats and edges, each looking every
33
+ * 2 s meanwhile, spent the relays' minute in those seconds and could not read the answers when they came: a group's
34
+ * edges were live again 75 and 110 s after a restart (bug hunt r5a, 2026-09-29).
35
+ */
36
+ export declare const OFFER_FAST_MS = 10000;
37
+ /**
38
+ * The longest wait between looks for an answer to an offer once it has been out `OFFER_FAST_MS`, in fast paces: 8 s on
39
+ * the relays (fast 2 s), 2.8 s on the DHT (0.7 s), which costs no relay budget.
40
+ */
41
+ export declare const OFFER_STEP_MAX = 4;
42
+ /** An offer to a saved contact is looked at for an answer as long as its attempt lasts (`CONNECT_TIMEOUT_MS`), not 45 s. */
43
+ export declare const OFFER_LOOK_MS = 90000;
44
+ /**
45
+ * How long a link looks fast when its peer, or the peer's offer, is due any moment. The peer that
46
+ * dials does so as soon as it sees the other one here, and its offer lands in its packet a moment
47
+ * after its presence did: without this the side that answers left the offer to a background poll
48
+ * (30 s on the relays), once on a group's entry session and once more per member edge.
49
+ */
50
+ export declare const EXPECT_PEER_MS = 30000;
51
+ /**
52
+ * How long a link keeps looking at the active pace after its contact went away from a live session (it said goodbye,
53
+ * or the session dropped): an app that restarts is back within this, and its dial or offer is seen in seconds.
54
+ */
55
+ export declare const WATCH_PEER_MS: number;
56
+ /**
57
+ * The longest a link reads fast for a data link whose connection went `disconnected` (`setDataLinkStalled`): a little
58
+ * past the 12 s such a connection is given (`DISCONNECT_GRACE_MS`), by when it is back or the session is gone.
59
+ */
60
+ export declare const STALLED_LOOK_MS = 15000;
61
+ /**
62
+ * For this long after its contact went away from a live session, a chat's reads of it say so (`PkarrRequestOptions.departed`):
63
+ * a few may go over the relays' budget (`DEPARTED_READS` in relay.ts). The fast window that follows a goodbye
64
+ * (`EXPECT_PEER_MS`): an app that restarts has its offer out well within it (2.5 to 10 s after its goodbye in the lab of
65
+ * #1441, on a loaded host), and past it the race's DHT dial has brought the chat back anyway.
66
+ */
67
+ export declare const DEPARTED_READ_MS = 30000;
68
+ /** A chat whose contact was never seen (an invite just sent) keeps looking at the active pace this long. */
69
+ export declare const AWAITING_PEER_MS: number;
70
+ /**
71
+ * A group link's peer whose packet advertises and carries no `_tr` on every read for this long publishes none: what it
72
+ * said before is forgotten (WISP 902 § Transports). Not at the first such packet: an app with no WebRTC (a Linux
73
+ * Desktop) publishes its `_tr` only once a native endpoint is up, seconds after its first packet of a run, and what it
74
+ * said in the run before still holds meanwhile. On this side's clock, from the first read that found it so.
75
+ */
76
+ export declare const TRANSPORTS_GONE_MS: number;
77
+ export declare const IDLE_THRESHOLD = 60000;
78
+ export declare const MAX_DHT_TEXT_BYTES = 500;
79
+ /** Presence is a fresh packet: advertising peers republish this often… */
80
+ export declare const PRESENCE_HEARTBEAT: number;
81
+ /** …and are considered gone once their packet is older than this. */
82
+ export declare const PRESENCE_WINDOW: number;
83
+ /** When this device first read the peer's latest packet, by its own clock (`PeerPresence.seenAt`). */
84
+ export declare const presenceSeenAt: (presence: Pick<PeerPresence, "lastPacketAt" | "seenAt">) => number;
85
+ export type LinkStatus = "connecting" | "online" | "offline" | "error";
86
+ export interface PeerPresence {
87
+ /** Peer advertises services and its packet is fresh. */
88
+ online: boolean;
89
+ /** Timestamp of the peer's latest packet (ms), 0 if none was ever seen. The peer's clock: it names the packet, and is never compared with this one's. */
90
+ lastPacketAt: number;
91
+ /**
92
+ * When this device first read that packet, by its own clock: what "how long ago" is measured from (`presenceSeenAt`).
93
+ * A packet is dated by its own time, held between the read of this run before the one that found it and that one: a
94
+ * few seconds apart while a link is being made, so the peer's clock no longer matters. The first read has no read
95
+ * before it: a peer whose clock is behind looks that much older until its next packet, and no peer's clock makes a
96
+ * packet look newer than the read that found it.
97
+ */
98
+ seenAt?: number;
99
+ nick?: string;
100
+ /** `null` for peers that do not advertise (legacy clients, or offline). */
101
+ services: ServiceAd[] | null;
102
+ }
103
+ export interface LinkSessionEvents {
104
+ onDiscoveryError?(error: string | null): void;
105
+ onMessages?(messages: ResolvedMessage[], batch: ResolvedLink): void;
106
+ onPresence?(presence: PeerPresence): void;
107
+ onPeerAck?(ackTimestamp: number): void;
108
+ onCallSignal?(signal: string): void;
109
+ /**
110
+ * `sight`: a read of the peer's record that the network answered, earlier in this run, did not have the signal
111
+ * (`SignalSight`): when that read began, and the time of the peer's packet it found, if any. Absent for a signal
112
+ * the first such read found.
113
+ */
114
+ onRtcSignal?(signal: string, sight?: SignalSight): void;
115
+ /**
116
+ * The peer's packet, dated `packetAt` by the peer's clock, was not there at this run's read of `readBefore` and is
117
+ * there at `readAt` (this clock): what its clock says against this one (`ClockWatch.peer`).
118
+ */
119
+ onPeerClock?(packetAt: number, readBefore: number, readAt: number): void;
120
+ /** The peer's packet carries a new `_tr` value (a group link's transports, `parsePacketTransports`). */
121
+ onPeerTransports?(value: string): void;
122
+ /** The peer's packet has said no `_tr` for `TRANSPORTS_GONE_MS`: the peer publishes none (any more). Once per such stretch. */
123
+ onPeerTransportsGone?(): void;
124
+ onStatus?(status: LinkStatus): void;
125
+ /** A poll started, or finished with the next one due in `nextInMs`. */
126
+ onPoll?(poll: {
127
+ polling: boolean;
128
+ nextInMs: number;
129
+ }): void;
130
+ /**
131
+ * A publish finished: how long it took, and whether it carried an `_rtc` signal. `error` when it failed; `waiting`
132
+ * when the relays' request budget held it back (nothing went out, and it goes again once the budget frees a request,
133
+ * in about `retryInMs`). `signalOut` when it is the first to carry the current `_rtc` signal: an offer or an answer went out now.
134
+ */
135
+ onPublish?(result: {
136
+ ms: number;
137
+ rtc: boolean;
138
+ error?: string;
139
+ waiting?: boolean;
140
+ retryInMs?: number;
141
+ signalOut?: boolean;
142
+ }): void;
143
+ /** The first read of the peer's key is done (with `firstPublish: "after-first-poll"`, what to publish is decided now). */
144
+ onFirstPoll?(): void;
145
+ }
146
+ export interface LinkSessionOptions {
147
+ params: LinkParams;
148
+ transport: PkarrTransport;
149
+ nick?: string;
150
+ /** Highest peer message timestamp already stored locally. */
151
+ lastSeenTimestamp?: number;
152
+ /** Services to advertise right now. Return undefined to advertise nothing. */
153
+ getServices?: () => ServiceAd[] | undefined;
154
+ pollIntervals?: PollIntervals;
155
+ events?: LinkSessionEvents;
156
+ /**
157
+ * When this side's first packet goes out. `at-start` (default): as the session starts. `after-first-poll`:
158
+ * once the peer's key was read, unless whoever asked publishes something better by then (a first
159
+ * pairing's joiner, who dials the moment it sees the inviter: its offer then travels in its first packet
160
+ * instead of a second one right behind it, which relays hold back for seconds), and in any case within
161
+ * `FIRST_PUBLISH_MAX_MS`.
162
+ */
163
+ firstPublish?: "at-start" | "after-first-poll";
164
+ /**
165
+ * When the chat was made, for a saved one: the wait for a peer never seen (`AWAITING_PEER_MS`) counts from then, not
166
+ * from this start. Counted from each start of the app, every saved chat whose contact had no packet at the relays
167
+ * (away for a day) was an invite just sent again: 50 of them read every 4 s for ten minutes, not in the background,
168
+ * and spent both relays' minute in the first seconds of a start, so nothing the app wrote (its DID record, a message
169
+ * sent at once) went out for a minute (2026-10-08).
170
+ */
171
+ awaitingSince?: number;
172
+ }
173
+ /** With `firstPublish: "after-first-poll"`, the first packet goes out by then whatever happened. */
174
+ export declare const FIRST_PUBLISH_MAX_MS = 2000;
175
+ export declare class LinkSession {
176
+ readonly identity: Identity;
177
+ readonly peerPubKeyZ32: string;
178
+ private readonly encKey;
179
+ private readonly transport;
180
+ private readonly events;
181
+ private readonly getServices;
182
+ private nick?;
183
+ private sentBuffer;
184
+ private myAck;
185
+ private lastSeenTimestamp;
186
+ private callSignal;
187
+ private rtcSignal;
188
+ private lastCallSignalIn;
189
+ /** The `_rtc` signal the last packet that went out carried. */
190
+ private rtcSignalOut;
191
+ private lastRtcSignalIn;
192
+ /** The `_rtc` signal the peer's packet carried as last read (null: none), whether or not it was new. */
193
+ private peerRtcSignal;
194
+ /** A group link's `_tr` value this side publishes (`setTransports`), and the last the peer's packet carried. */
195
+ private transports;
196
+ private lastTransportsIn;
197
+ /** When a read first found the peer's packet advertising with no `_tr` (0: the last packet that said carried one). */
198
+ private transportsAbsentSince;
199
+ private transportsGone;
200
+ private running;
201
+ /** Stopped without a last packet (`stop(false)`): nothing more goes out. */
202
+ private silent;
203
+ private polling;
204
+ /** `lookNow` came during a read: the next one follows it at once. */
205
+ private pollAgain;
206
+ private publishing;
207
+ private publishAgain;
208
+ /** What waits to go out is the presence heartbeat alone (`PRESENCE_HEARTBEAT`): nothing in the packet changed. */
209
+ private upkeepOnly;
210
+ private pollTimer;
211
+ private heartbeatTimer;
212
+ private lastActivity;
213
+ private readonly startedAt;
214
+ /** From when a peer never seen is awaited (`AWAITING_PEER_MS`): never later than this start, whatever the clock said when the chat was made. */
215
+ private readonly awaitingSince;
216
+ private readonly intervals;
217
+ private fastPollUntil;
218
+ /** An offer to a saved contact is out: from then on its fast window looks less often (`OFFER_FAST_MS`); 0 for none. */
219
+ private fastStepsAfter;
220
+ /** When the last `expectPeer` window ends (or ended): the pace slows down from there step by step. */
221
+ private expectUntil;
222
+ private watchUntil;
223
+ /** The time of the peer's packet read last when it went away (`watchPeer`): a newer one that advertises says it is back. */
224
+ private watchFrom;
225
+ /** Until when the reads of a contact that went away are its first ones (`DEPARTED_READ_MS`). */
226
+ private departedUntil;
227
+ private publishRetryTimer;
228
+ private active;
229
+ private connected;
230
+ /** The open data link's connection is `disconnected`, and read fast until then (`setDataLinkStalled`). */
231
+ private stalledUntil;
232
+ private readonly firstPublish;
233
+ private firstPublishTimer;
234
+ private firstPollDone;
235
+ /** When this side last published (0: never). */
236
+ lastPublishedAt: number;
237
+ /** A publish is in flight, or finished this recently: another packet now would only queue behind it at the relays. */
238
+ publishedRecently(withinMs: number): boolean;
239
+ private discoveryErrors;
240
+ /** The last read was not answered by the network: it failed, or the transport handed back a copy it kept (`discoveryRecovered`). */
241
+ private readMissed;
242
+ private unsubscribe;
243
+ private presence;
244
+ /**
245
+ * When the last read of the peer's record that the network answered began (0: none yet in this run). A read that
246
+ * handed back a copy kept from before (`PkarrTransport.readAnsweredAt`) is not one: it says nothing of what the
247
+ * record holds now.
248
+ */
249
+ private lastReadAt;
250
+ /** The latest time of the peer's own packets those reads found, by the peer's clock (0: none; the inviter's empty packet is not the peer's). */
251
+ private peerPacketAt;
252
+ constructor(options: LinkSessionOptions);
253
+ get peerPresence(): PeerPresence;
254
+ /** The `_rtc` signal the peer's packet carries, as last read: null when it carries none. */
255
+ get peerSignal(): string | null;
256
+ start(): void;
257
+ /**
258
+ * A relay answers again after failing. What this link could not do meanwhile goes now: a publish that waits, and a
259
+ * read when its last one was not answered by the network (it failed, or handed back a copy kept from before) or when
260
+ * the link is looking for its peer (anything but the background and connected paces). A link whose last read was
261
+ * answered missed nothing: it reads at its pace. Every link heard this, so a read each one made the cost of a relay
262
+ * that keeps flipping between throttled and answering grow with the number of chats: 42 reads a flip on a profile
263
+ * whose contacts are mostly away, for nothing those reads could find.
264
+ */
265
+ private discoveryRecovered;
266
+ /** This side's packet goes out now, unless one already did. */
267
+ ensureAdvertised(): void;
268
+ /** This side's packet goes out again as it is: another writer of its key (a second device on a device code) may have replaced it. */
269
+ republish(): void;
270
+ /** Stops the loops. With `announce`, first tells the peer we are gone. */
271
+ stop(announce?: boolean): Promise<void>;
272
+ setNick(nick: string | undefined): void;
273
+ /** The user is looking at this link: poll at chat speed. */
274
+ setActive(active: boolean): void;
275
+ /**
276
+ * Signaling in progress: look fast. `offer`: this side's offer to a saved contact, whose answer may be a while
277
+ * (`OFFER_FAST_MS`): fast at first, then less often.
278
+ */
279
+ setFastPoll(fast: boolean, offer?: boolean): void;
280
+ /**
281
+ * The peer, or its offer, is due any moment: poll fast for `EXPECT_PEER_MS` (never cutting a longer fast window short),
282
+ * then slow down step by step (`nextInterval`) rather than at once.
283
+ */
284
+ expectPeer(): void;
285
+ /**
286
+ * The contact just left a live session, and is likely coming back (an app restarting): fast for `EXPECT_PEER_MS`,
287
+ * then the active pace until `WATCH_PEER_MS` passed, whatever the chat's pace would be.
288
+ */
289
+ watchPeer(): void;
290
+ /** The data link carries chat and services while it is up. */
291
+ setDataLinkOpen(open: boolean): void;
292
+ /**
293
+ * The open data link's connection went `disconnected` (true), or came back: the contact's app may have crashed, and
294
+ * once it starts again its offer is on Pkarr, which nothing on a dead data link says. Read fast for as long as it
295
+ * lasts (the connection is given up or back within seconds), not at the connected pace. One read as it went
296
+ * `disconnected` found only an offer already out: an app back a moment later (a tab opened again by hand) waited for
297
+ * the connection's grace to run out (web/restart-relink.spec.ts, 20 s on a busy machine). Never longer than
298
+ * `STALLED_LOOK_MS`, whatever becomes of the connection.
299
+ */
300
+ setDataLinkStalled(stalled: boolean): void;
301
+ setCallSignal(signal: string | null): Promise<void>;
302
+ /** Includes encryption, DNS encoding and the actual concurrent record budget. */
303
+ fitsRtcSignal(signal: string): boolean;
304
+ /**
305
+ * A group link's transports and how to dial them (`_tr`, `encodePacketTransports`): published with the next packet,
306
+ * now if it changed. `null` publishes none, which is what every link but a group's with an app lacking WebRTC does.
307
+ */
308
+ setTransports(value: string | null): void;
309
+ setRtcSignal(signal: string | null, reportFailure?: boolean): Promise<void>;
310
+ /**
311
+ * Hands over the messages the peer has not acknowledged, for delivery over
312
+ * the data link. That channel is reliable, so they leave the Pkarr buffer.
313
+ */
314
+ takeUnacknowledged(): CompactMessage[];
315
+ /** Call after the list of shared services changed. A first publish still being held back will say it all. */
316
+ refreshAdvertisement(): Promise<void>;
317
+ /** Sends a chat message through Pkarr. Returns an error string, or null on success. */
318
+ sendMessage(text: string, timestamp?: number): Promise<string | null>;
319
+ pollNow(): void;
320
+ /**
321
+ * The peer's packet is at hand now (a member of the group carried it, `CarriedTransport`): read it. A read under way
322
+ * may be past the point where it would see it, so another follows that one at once rather than at the pace's wait.
323
+ */
324
+ lookNow(): void;
325
+ /**
326
+ * The next poll's wait. After a window that looked fast for the peer (`expectPeer`), the wait grows with the time
327
+ * since the window ended (on the relays: 4, 4, 8, 16 s, then 30 s) up to the pace's own. A
328
+ * peer's offer held back by its relays' budget lands whenever that frees a request: it used to land seconds after
329
+ * the window, and wait out a whole background poll (30 s) there (2026-09-27). About three more reads a window that
330
+ * ends with no offer.
331
+ */
332
+ private nextInterval;
333
+ /**
334
+ * Looking for a contact that went away (`watchPeer`) and has not shown itself back: no signal of mine is out, and no
335
+ * packet of the contact's since then advertises (the one it leaves on its way out does not). The relays' budget gives
336
+ * these reads a share of its own (`PkarrRequestOptions.watch`), so a member watching several that left still reads
337
+ * the one that comes back.
338
+ */
339
+ private watching;
340
+ /** How urgently this link looks right now. */
341
+ private pace;
342
+ private scheduleHeartbeat;
343
+ /**
344
+ * Coalesces publishes: at most one in flight and one queued behind it. `upkeep`: nothing new to say (the heartbeat, a
345
+ * retry of what waits): with nothing else asked for since, the packet goes as upkeep (`publishOnce`).
346
+ */
347
+ private publish;
348
+ private publishOnce;
349
+ /** When a publish that failed goes again: when the relays' budget frees a request, if that held it back. */
350
+ private retryDelay;
351
+ private discoveryResult;
352
+ private poll;
353
+ }
@@ -0,0 +1,60 @@
1
+ /**
2
+ * A link preview as it travels with a chat message (WISP 401 § Link previews): what the sender's app read from the
3
+ * page when the message was written, carried in the message so the reader never contacts the site. Every field
4
+ * but the link is optional. The receiver checks it here and drops it, never the message, when anything is off.
5
+ */
6
+ export interface LinkPreview {
7
+ /** The link the preview is of: a link of the message's text, without its tracking parameters (`canonicalUrl`). */
8
+ u: string;
9
+ /** The page's title. */
10
+ t?: string;
11
+ /** Its description. */
12
+ d?: string;
13
+ /** The site's name ("YouTube"). */
14
+ s?: string;
15
+ /** A thumbnail redrawn by the sender: a JPEG `data:` URL (`LINK_PREVIEW_LIMITS.imageBytes`, `imageSide`). */
16
+ i?: string;
17
+ }
18
+ export declare const LINK_PREVIEW_LIMITS: {
19
+ readonly urlChars: 2048;
20
+ readonly titleChars: 200;
21
+ readonly descriptionChars: 300;
22
+ readonly siteChars: 80;
23
+ /** The thumbnail's JPEG bytes. Ghostly draws it at most 320 pixels wide and fits it under this. */
24
+ readonly imageBytes: 20000;
25
+ /** The largest side a thumbnail may declare in its header (a tiny file can claim a huge image). */
26
+ readonly imageSide: 640;
27
+ /** The preview as JSON. With a text of 16 KiB the message frame stays under the 60 KiB a session takes. */
28
+ readonly jsonChars: number;
29
+ };
30
+ /**
31
+ * A link ends where the sentence around it takes over: trailing punctuation ("see https://x.example/a.") and a
32
+ * closing bracket or quote the link did not open ("(https://x.example/a)") are left as text. The same rule as the
33
+ * message bubble's links.
34
+ */
35
+ export declare function linkEnd(url: string): string;
36
+ /** Characters of a link worth reading: a longer one is no address anyone shares, and is left as text. */
37
+ export declare const LINK_MAX_CHARS: number;
38
+ /** The http(s) links of a text, in order, each ending as the bubble ends it. */
39
+ export declare function linksIn(text: string): string[];
40
+ /**
41
+ * The link as a preview names it: parsed, http(s) only, without tracking parameters (`utm_*`, `fbclid`, …). The
42
+ * other parameters keep their order and spelling. Null for anything that is not an http(s) URL.
43
+ */
44
+ export declare function canonicalUrl(link: string): string | null;
45
+ /**
46
+ * A thumbnail's size in pixels, from its JPEG header: a card keeps its box before the picture decodes. Undefined for
47
+ * anything but a JPEG data URL within the limits.
48
+ */
49
+ export declare function previewImageSize(value: unknown): {
50
+ width: number;
51
+ height: number;
52
+ } | undefined;
53
+ /** The thumbnail if it is one Ghostly shows: a JPEG data URL within the limits whose header declares a sane size. */
54
+ export declare function sanitizePreviewImage(value: unknown): string | undefined;
55
+ /**
56
+ * A preview as a message may carry it, or undefined. `text` is the message's: the preview must be of one of its
57
+ * links (compared without tracking parameters), so a card can never point somewhere the text does not. Titles and
58
+ * descriptions are cut to their limits; a bad thumbnail is dropped and the rest kept.
59
+ */
60
+ export declare function parseLinkPreview(raw: unknown, text: string): LinkPreview | undefined;
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Timestamps along a paired link's way to a live connection, for measuring where the time goes.
3
+ * Silent unless `globalThis.__ghostlyLinkTrace` is set (the e2e measurements set it): each step is
4
+ * then one `console.debug` line, `[ghostly:link] {"t":…,"me":…,"step":…}`, read back by the test.
5
+ * A host may also install a sink (the desktop app writes the lines to its log file), which gets every
6
+ * line whether or not the global is set.
7
+ */
8
+ type LinkTraceSink = (line: string) => void;
9
+ /** Where the lines go besides the console; `null` removes it. */
10
+ export declare function setLinkTraceSink(next: LinkTraceSink | null): void;
11
+ export declare function traceLink(me: string, step: string, detail?: Record<string, unknown>): void;
12
+ export {};
@@ -0,0 +1,99 @@
1
+ import { type Bolt11Invoice } from "./bolt11.js";
2
+ /**
3
+ * Paying a Lightning address or an LNURL: the payer's side of
4
+ * [LUD-16](https://github.com/lnurl/luds/blob/luds/16.md) (`name@domain`),
5
+ * [LUD-06](https://github.com/lnurl/luds/blob/luds/06.md) (`payRequest`),
6
+ * [LUD-01](https://github.com/lnurl/luds/blob/luds/01.md) (`lnurl1…` bech32),
7
+ * [LUD-17](https://github.com/lnurl/luds/blob/luds/17.md) (`lnurlp://`),
8
+ * [LUD-12](https://github.com/lnurl/luds/blob/luds/12.md) (a comment) and
9
+ * [LUD-09](https://github.com/lnurl/luds/blob/luds/09.md) (a success message).
10
+ *
11
+ * Resolving reveals the request to the service's domain (it is an HTTPS fetch), so the domain is part of
12
+ * what a person is shown before anything is fetched. Everything the service answers is checked: the
13
+ * amounts it allows, the invoice it returns (its amount, and that it commits to the metadata the person
14
+ * saw), and how much of it is read at all. Paying then goes through the active Lightning source like any
15
+ * other invoice. Receiving on a Lightning address needs a server the person runs; it is not here.
16
+ */
17
+ export interface LightningDestination {
18
+ kind: "address" | "lnurl";
19
+ /** What was pasted, normalised: a lower-cased `name@domain`, or the `lnurl…` / `lnurlp://…` text. */
20
+ text: string;
21
+ /** Where the pay request is fetched from. */
22
+ url: string;
23
+ /** The host that learns about the request. */
24
+ domain: string;
25
+ /** LUD-16: the part before the `@`. */
26
+ name?: string;
27
+ }
28
+ export interface LnurlSuccessAction {
29
+ tag: "message" | "url";
30
+ message?: string;
31
+ description?: string;
32
+ url?: string;
33
+ }
34
+ /** A service's `payRequest`, checked. Amounts in `minSendable`/`maxSendable` are millisats, `minSat`/`maxSat` whole sats. */
35
+ export interface LnurlPayParams {
36
+ destination: LightningDestination;
37
+ callback: string;
38
+ /** The host the invoice is asked from, when it is not the one that answered. */
39
+ callbackDomain: string;
40
+ minSendable: number;
41
+ maxSendable: number;
42
+ minSat: number;
43
+ maxSat: number;
44
+ /** The metadata string as the service sent it: what the invoice must commit to. */
45
+ metadata: string;
46
+ /** sha256 of `metadata`, hex: the invoice's `h` tag when it has one. */
47
+ descriptionHash: string;
48
+ /** The `text/plain` entry: what the payment is for, as the service says. */
49
+ description: string;
50
+ /** The `text/identifier` or `text/email` entry, when the service names an address. */
51
+ identifier?: string;
52
+ /** LUD-12: how long a comment may be; 0 when none is taken. */
53
+ commentAllowed: number;
54
+ }
55
+ export interface LnurlFetchOptions {
56
+ fetch?: typeof fetch;
57
+ signal?: AbortSignal;
58
+ timeoutMs?: number;
59
+ maxBytes?: number;
60
+ }
61
+ export declare const LNURL_LIMITS: {
62
+ readonly timeoutMs: 15000;
63
+ readonly maxBytes: number;
64
+ readonly maxRedirects: 5;
65
+ readonly maxUrlLength: 2048;
66
+ readonly maxMetadataLength: number;
67
+ readonly maxComment: 2000;
68
+ };
69
+ /** A Lightning address or LNURL inside free text: `lightning:` and `⚡` prefixes are tolerated. */
70
+ export declare const LIGHTNING_DESTINATION_PATTERN: RegExp;
71
+ /** Reads what was pasted as a Lightning address or an LNURL; null when it is neither. Throws when it is one, but a bad one. */
72
+ export declare function parseLightningDestination(input: string): LightningDestination | null;
73
+ /** The first Lightning address or LNURL in a message, with whatever else the message says. */
74
+ export declare function findLightningDestination(text: string): {
75
+ destination: LightningDestination;
76
+ rest: string;
77
+ } | null;
78
+ /** One GET to an LNURL service (and to each checked redirect of it): bounded in time and size, no credentials, no referrer, and the answer must be JSON. */
79
+ export declare function fetchLnurlJson(url: string, options?: LnurlFetchOptions): Promise<unknown>;
80
+ /** Checks a service's `payRequest` answer (LUD-06), and reads what a person needs to see of it. */
81
+ export declare function parsePayParams(body: unknown, destination: LightningDestination): LnurlPayParams;
82
+ /** Where to ask for the invoice of `amountSat` (and a comment, LUD-12). Throws when the amount or comment is not allowed. */
83
+ export declare function invoiceCallbackUrl(params: LnurlPayParams, amountSat: number, comment?: string): string;
84
+ /**
85
+ * Checks the invoice a service answered with (LUD-06): the amount asked, a payment hash, not expired, and
86
+ * a commitment to the metadata the person was shown: the `h` tag is its sha256, or the invoice carries the
87
+ * metadata itself as its description (the same commitment, unhashed).
88
+ */
89
+ export declare function parseInvoiceCallback(body: unknown, params: LnurlPayParams, amountSat: number): {
90
+ invoice: Bolt11Invoice;
91
+ successAction?: LnurlSuccessAction;
92
+ };
93
+ /** Fetches and checks what a Lightning address or LNURL asks for. The service's domain learns of it. */
94
+ export declare function resolveLightningDestination(text: string, options?: LnurlFetchOptions): Promise<LnurlPayParams>;
95
+ /** Asks the service for an invoice of `amountSat`, and checks it before it is handed to any wallet. */
96
+ export declare function requestLnurlInvoice(params: LnurlPayParams, amountSat: number, comment: string | undefined, options?: LnurlFetchOptions): Promise<{
97
+ invoice: Bolt11Invoice;
98
+ successAction?: LnurlSuccessAction;
99
+ }>;