@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,234 @@
1
+ import { type Identity } from "./identity.js";
2
+ import type { LinkParams } from "./invite.js";
3
+ import type { PairingCredentials } from "./pairedSession.js";
4
+ import { type TransportDescriptors } from "./pairedTransports.js";
5
+ import { type GhostRecord, type SignedPacket } from "./pkarr.js";
6
+ import { type PkarrTransport } from "./transport.js";
7
+ /**
8
+ * The layer-0 capability record of a chat (WISP 03, revision 0.2): what each side accepts on the DHT
9
+ * (`dht-text/1`, `hold/1`), what its layer 1 would carry, the minimum to dial its native transports
10
+ * without a WebRTC session first, and the name it shares. One Pkarr key per direction, derived from the
11
+ * invite secret like the DHT mailboxes, so its size never competes with a text.
12
+ *
13
+ * Sealed with the invitation-derived key until the contact is pinned, and with a key only the two
14
+ * participation keys derive afterwards, so a copied invite stops reading it. Always signed by the
15
+ * author's participation key over both rendezvous keys.
16
+ */
17
+ export declare const DHT_TEXT_CAPABILITY: "dht-text/1";
18
+ export declare const CAPS_LABEL = "_caps";
19
+ export declare const CAPS_LIMITS: {
20
+ readonly versions: 8;
21
+ readonly transports: 8;
22
+ readonly capabilities: 32;
23
+ readonly extensions: 32;
24
+ /** One identifier, capability or extension. */
25
+ readonly itemChars: 48;
26
+ readonly nameBytes: 64;
27
+ };
28
+ /**
29
+ * How far before its own clock an author dates a record (`issued`). No reader orders records by that time, `rev` does,
30
+ * and this one refuses none for it. Apps up to 1.0.2 refuse a record dated more than a minute past their clock: one
31
+ * dated by a clock two minutes ahead was never read by them, with nothing on screen, and the chat could not dial its
32
+ * contact's native transports before a session. Dated back, a record from a clock up to about eleven minutes ahead is
33
+ * taken by them too.
34
+ */
35
+ export declare const CAPS_ISSUED_BACK_MS: number;
36
+ /** Published again this often while the chat exists, so it does not age out of the DHT. */
37
+ export declare const CAPS_REFRESH_MS: number;
38
+ /**
39
+ * Changes closer together than this go out as one publication, the last: every publication spends one of the
40
+ * relays' requests per relay, a budget the chat's signaling needs more.
41
+ */
42
+ export declare const CAPS_PUBLISH_SPACING_MS = 30000;
43
+ /**
44
+ * Per native transport, the minimum to dial it: no network address, ever. Keys travel as base64url (32
45
+ * bytes, 43 characters) to leave the packet room for capabilities.
46
+ */
47
+ export interface CapsDescriptors {
48
+ "iroh/1"?: {
49
+ id: string;
50
+ relay?: string;
51
+ };
52
+ /** `relay`: a browser's HyperDHT is reached through a relay server, which it names (a public service, not its address). */
53
+ "hyperdht/1"?: {
54
+ publicKey: string;
55
+ relay?: string;
56
+ };
57
+ }
58
+ export interface CapsContent {
59
+ versions: number[];
60
+ /** Layer-1 transports this runtime has, in local preference order. Never the DHT. */
61
+ transports: string[];
62
+ capabilities: string[];
63
+ extensions: string[];
64
+ descriptors: CapsDescriptors;
65
+ /** The name this profile shares with contacts; empty when it shares none. */
66
+ name: string;
67
+ /**
68
+ * The layer-1 transport chosen for this chat in its Connection menu, absent on Automatic (WISP 100, "A choice made
69
+ * while not live"). It reaches a contact that has no session to hear a switch intent on. A trailing element: apps
70
+ * from before it ignore it.
71
+ */
72
+ choice?: string;
73
+ }
74
+ export interface CapsRecord extends CapsContent {
75
+ rev: number;
76
+ issued: number;
77
+ /** The participation key that signed it. */
78
+ author: string;
79
+ }
80
+ export type CapsRefusal = "address" | "size" | "sealed" | "format" | "signature" | "author" | "rev";
81
+ /** Why a record was not used. A refused record leaves the last good one in force. */
82
+ export declare class CapsRefusedError extends Error {
83
+ readonly reason: CapsRefusal;
84
+ constructor(reason: CapsRefusal, message: string);
85
+ }
86
+ /**
87
+ * The part of the native descriptors a capability record may carry: the Iroh endpoint id (and the relay
88
+ * it is reachable through, a public service rather than an address of this device), the HyperDHT key.
89
+ */
90
+ export declare function capsDescriptors(descriptors: TransportDescriptors | undefined): CapsDescriptors;
91
+ /**
92
+ * A record's descriptors as the transport adapters dial them. With no address in the record, an Iroh path is
93
+ * relayed; a HyperDHT that names a relay (a browser's) is too: both rank after direct paths and before the DHT
94
+ * floor (WISP 100, "Relayed"), and a first contact can dial them before WebRTC has failed.
95
+ */
96
+ export declare function dialDescriptors(descriptors: CapsDescriptors): TransportDescriptors;
97
+ /**
98
+ * A group link's transports in its own packet (`_tr`, WISP 902 § Transports): a group's edge or entry session has no
99
+ * capability record, so an app with no WebRTC (the Linux Desktop) says there which layer-1 transports it runs and how to
100
+ * dial its native ones, and a member's app that has WebRTC answers in kind. The same minimum a record carries: keys and
101
+ * relays, never an address. Sealed with the link key like every other label of the packet.
102
+ */
103
+ export interface PacketTransports {
104
+ transports: PairedTransportName[];
105
+ descriptors: CapsDescriptors;
106
+ }
107
+ type PairedTransportName = "iroh/1" | "hyperdht/1" | "webrtc/1";
108
+ /** The `_tr` value: `{"t": transports, "d": descriptors}`, versionless and additive (an unknown field is ignored). */
109
+ export declare function encodePacketTransports(transports: readonly string[], descriptors: TransportDescriptors | undefined): string;
110
+ /** A `_tr` value read from a packet; null when it is not one (a reader drops it, as a record it cannot read). */
111
+ export declare function parsePacketTransports(json: string | null): PacketTransports | null;
112
+ /** Keys of the capability record of one link: my record's key and seals, the contact's address. */
113
+ export declare class CapsKeys {
114
+ readonly from: string;
115
+ readonly to: string;
116
+ readonly me: string;
117
+ /** Publishes my record. */
118
+ readonly identity: Identity;
119
+ /** Where the contact publishes its record. */
120
+ readonly peerAddress: string;
121
+ private readonly seed;
122
+ private readonly inviteKey;
123
+ constructor(params: LinkParams, participationSeedB64: string);
124
+ private pinnedKey;
125
+ private signable;
126
+ /**
127
+ * My record as Pkarr records, sealed for the pinned contact (or with the invite key before the pin).
128
+ * Past 1,000 bytes the name goes first, then the extensions; capabilities and transports are never cut.
129
+ */
130
+ seal(content: CapsContent, rev: number, peerKey?: string, now?: number): {
131
+ records: GhostRecord[];
132
+ dropped: ("name" | "extensions")[];
133
+ };
134
+ /**
135
+ * The contact's record, checked: its address, its seal, a well-formed body, a signature by the pinned
136
+ * participation key (before the pin, by `expected` when a first contact named one) and not older than `minRev`.
137
+ *
138
+ * Its `issued` is the author's word on its own clock and refuses nothing. A record is the author's alone (signed by
139
+ * its participation key, bound to both rendezvous keys), and an older one cannot take a newer one's place because of
140
+ * `rev`, which the reader keeps. Refusing a record dated over a minute ahead added nothing to that, and cost every
141
+ * contact whose clock runs a couple of minutes fast its record.
142
+ */
143
+ open(packet: SignedPacket, options?: {
144
+ pinned?: string;
145
+ expected?: string;
146
+ minRev?: number;
147
+ }): CapsRecord;
148
+ }
149
+ export interface CapsState {
150
+ /** My record's revision: increases with every change of its content. */
151
+ rev: number;
152
+ /**
153
+ * A digest of the content of revision `rev`, and when it was last published, and whether sealed for the pinned
154
+ * contact. No `publishedAt`: that revision is not known to be out (a publication failed, or was cut short), and goes
155
+ * out at the next look.
156
+ */
157
+ digest?: string;
158
+ publishedAt?: number;
159
+ sealedFor?: string;
160
+ /** The contact's last good record. */
161
+ peer?: CapsRecord;
162
+ }
163
+ export declare const emptyCapsState: () => CapsState;
164
+ /**
165
+ * Publishes this side's record (at first start, at every change, hourly) and reads the contact's (at
166
+ * pairing, when an envelope names a newer revision, when the chat drops to the DHT). Publications go one
167
+ * at a time, and reads one at a time beside them (a read never waits for a put); reads close together are merged.
168
+ */
169
+ export declare class CapsExchange {
170
+ private readonly options;
171
+ private state;
172
+ private readonly keys;
173
+ /** Publications, one at a time; reads of the contact's record (another key) have their own, so neither waits for the other. */
174
+ private chain;
175
+ private readChain;
176
+ private saveChain;
177
+ private timer;
178
+ private running;
179
+ private lastRead;
180
+ private readTimer;
181
+ /** The newest revision of the contact's record an envelope named, and the reads made again since for it. */
182
+ private named;
183
+ private retries;
184
+ private retryTimer;
185
+ /** What the last publication of this run carried. */
186
+ private lastOut?;
187
+ private dropped;
188
+ constructor(options: {
189
+ params: LinkParams;
190
+ credentials: PairingCredentials;
191
+ transport: PkarrTransport;
192
+ local(): CapsContent;
193
+ state?: CapsState;
194
+ save(state: CapsState): Promise<void>;
195
+ /** The contact's record changed (a newer revision was read). */
196
+ changed?(record: CapsRecord): void;
197
+ /** A new revision of this side's record went out: the contact learns of it from an envelope that names it. */
198
+ published?(rev: number): void;
199
+ /** A record was refused; `author` is a security signal (another key signed under this chat's address). */
200
+ refused?(error: CapsRefusedError): void;
201
+ });
202
+ get rev(): number;
203
+ get peer(): CapsRecord | undefined;
204
+ /** What had to be left out to fit the packet at the last publication. */
205
+ get droppedFields(): readonly ("name" | "extensions")[];
206
+ get address(): string;
207
+ private serialize;
208
+ /** Saves are one at a time, each over the state as it is then: a read and a publication change different fields. */
209
+ private persist;
210
+ start(): void;
211
+ /** Stopped for good: a start still waiting (the engine starts it once the chat's endpoints are up) does nothing. */
212
+ private ended;
213
+ stop(): Promise<void>;
214
+ /**
215
+ * Publishes when the content changed, when the contact was pinned since the last publication (the
216
+ * record is sealed anew for it), or when the last one is an hour old. Otherwise nothing goes out.
217
+ */
218
+ update(): Promise<void>;
219
+ private schedule;
220
+ /** An envelope named this revision of the contact's record: read it when it is newer than the one known. */
221
+ peerRev(rev: number): void;
222
+ /** Reads the contact's record now (or right after the last read, when that was a moment ago). */
223
+ refresh(force?: boolean): void;
224
+ /** Reads and checks the contact's record; the last good one stays when this one is refused. */
225
+ read(): Promise<CapsRecord | undefined>;
226
+ /**
227
+ * Read again in a moment, a few times at most, while the record known is short of what the contact has: of the
228
+ * revision an envelope named, or of a descriptor for a native transport it lists (its endpoint was still starting)
229
+ * that this side runs too. Its next revision, with the descriptor, is named only once, by an envelope that may
230
+ * come before the record is out; without it neither side could dial the other.
231
+ */
232
+ private readAgainIfBehind;
233
+ }
234
+ export {};
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Frames of one catch-up answer in a slice, two slices at most not handled yet by the member's app: the next goes once
3
+ * it handled the one before the last. An app holds 64 frames waiting at most before 2026-10-07 (more ends the session),
4
+ * and a member back in a busy group was handed over a hundred at once (a private group's answer, WISP 902; a
5
+ * community's, WISP 903: 258 from a full store).
6
+ */
7
+ export declare const CATCH_UP_SLICE = 16;
8
+ /** Between two slices, when the member's app cannot say it handled one (`handled` resolves `false`). */
9
+ export declare const CATCH_UP_PAUSE_MS = 500;
10
+ /** What `CatchUpHooks.handled` says: handled, cannot tell (`false`), or not handled yet within its wait (`"late"`). */
11
+ export type CatchUpHandled = boolean | "late";
12
+ export interface CatchUpHooks<F> {
13
+ /** One frame to the member: `false` when its edge did not take it, which ends the answer. */
14
+ send(to: string, frame: F): boolean | void;
15
+ /**
16
+ * Resolves once the member's app handled every frame sent to it so far (it answers a ping in the order frames come),
17
+ * or `false` when it cannot tell: the answer then waits `CATCH_UP_PAUSE_MS` between slices. `"late"`: the member's app
18
+ * answers pings but has not handled them yet (a phone with a long history), and the answer asks again rather than
19
+ * sending more. Absent: an answer goes all at once, as before 2026-10-07.
20
+ */
21
+ handled?(to: string): Promise<CatchUpHandled>;
22
+ /** Whether the group still answers: an answer stops when it no longer does. */
23
+ active(): boolean;
24
+ }
25
+ /**
26
+ * Catch-up answers, a slice at a time (`CATCH_UP_SLICE`), with two slices at most not handled yet by the member's app
27
+ * (`hooks.handled`): the next once it handled the one before the last, so the slices follow each other without a round
28
+ * trip between them. All at once, a member back in a busy group was handed over a hundred frames on one session, and an
29
+ * app that holds 64 waiting ended that session mid catch-up ("Session receive limit exceeded", 2026-10-07). The frames
30
+ * and their order are what they were: only when they go changes.
31
+ */
32
+ export declare class CatchUpAnswers<F> {
33
+ private readonly hooks;
34
+ /** Answers still going out, per member: what is left of each. */
35
+ private going;
36
+ constructor(hooks: CatchUpHooks<F>);
37
+ /**
38
+ * The first two slices go now, the rest without holding the group's other frames back. A newer answer to the same
39
+ * member takes the place of what is left of the last; a frame the edge did not take ends it (the member asks again
40
+ * when its edge opens).
41
+ */
42
+ handOut(to: string, frames: F[]): void;
43
+ /** The next slice of `rest` to `to`: false, and nothing left, when the edge did not take one. */
44
+ private sendSlice;
45
+ }
@@ -0,0 +1,271 @@
1
+ import { type FileInfo } from "./files.js";
2
+ /**
3
+ * files/3 (WISP 501, revision 0.3): files of any size in a chat, offered before they are sent, sent with
4
+ * many chunks in flight, resumed from the last confirmed byte after a drop, a transport switch or a
5
+ * restart, and checked against the sender's SHA-256 once stored.
6
+ *
7
+ * One `ChatFiles` per chat lives as long as the app does, across sessions: `attach` when a session that
8
+ * agreed `files/3` is open, `detach` when it goes. Records (`FileTransferRecord`) are the state that
9
+ * survives a restart; the host keeps them and hands them back with `restore`.
10
+ *
11
+ * Frames (authenticated JSON on the paired session):
12
+ *
13
+ * sender → receiver pf-offer {id,name,mime,size,ts,voice?,video?,image?,r?,paused?} pf-data {id,offset,data}
14
+ * pf-sum {id,size,digest} pf-abort {id}
15
+ * receiver → sender pf-accept {id,offset} pf-wait {id,why} pf-got {id,offset} pf-done {id}
16
+ * pf-refuse {id,why,room?}
17
+ * both pf-room {max}
18
+ *
19
+ * The offer is repeated on every session until the transfer ends, so every answer is idempotent: the
20
+ * receiver says where it stands (accept from an offset, wait, done, refuse) and the sender goes on from
21
+ * there. Nothing but the offset a receiver confirms moves a sender forward. A receiver may say `pf-accept`
22
+ * again at any time (nothing arrived for a while, or its person asked again): the sender goes on from that offset.
23
+ * What a sender sends again that way is bounded (`FILE_LIMITS.resendBytes`, and the host's `resend`): past it the
24
+ * sender ends the transfer.
25
+ */
26
+ export declare const FILE_LIMITS: {
27
+ /** Bytes in one `pf-data` frame: a frame stays far below the 60 KiB a session carries. */
28
+ readonly chunkBytes: number;
29
+ /** Bytes a sender has sent and not seen confirmed: throughput is this per round trip. */
30
+ readonly windowBytes: number;
31
+ /** A receiver asks its person before taking a file larger than this. */
32
+ readonly askAboveBytes: number;
33
+ /** Files taken without asking, per contact, while stored. Past it, every file is asked about. */
34
+ readonly autoAcceptBytesPerPeer: number;
35
+ /** Offers from one contact waiting for an answer here. */
36
+ readonly maxWaitingOffers: 16;
37
+ /** Files one contact sends at once; accepted ones beyond wait their turn. */
38
+ readonly maxActiveIncoming: 3;
39
+ /** An offer nobody answered ends after this long. */
40
+ readonly offerTtlMs: number;
41
+ /**
42
+ * No answer while something is outstanding: the sender offers again, which puts both sides back in step. Nothing
43
+ * arriving for a file under way: the receiver says again where it stands.
44
+ */
45
+ readonly idleMs: 30000;
46
+ /**
47
+ * A transfer that has not moved for this long (or not since the app started) offers its person "Send again" or
48
+ * "Ask again". Longer than `idleMs`, so what happens on its own has its turn first.
49
+ */
50
+ readonly stallMs: 60000;
51
+ /** A receiver makes what it stored durable, and records the point to resume from, this often. */
52
+ readonly checkpointBytes: number;
53
+ /** A receiver confirms at least this often while writing. */
54
+ readonly ackEveryBytes: number;
55
+ /** A sender reads its file this much at a time. */
56
+ readonly readBytes: number;
57
+ /** The session refused a data frame (its send budget was full): the sender looks again after this long. */
58
+ readonly sendRetryMs: 250;
59
+ /**
60
+ * What a sender sends of one file beyond its size (parts sent again after a drop, a restart of the receiver, or a
61
+ * `pf-accept` from an earlier offset): twice the file's size and this much. Past it the sender ends the transfer (WISP 501 § Resume).
62
+ */
63
+ readonly resendBytes: number;
64
+ };
65
+ export declare const FILE_FRAMES: Set<string>;
66
+ export type TransferState =
67
+ /** Out: waiting for a session to offer it on. In: accepted, waiting for its turn or for the sender. */
68
+ "queued"
69
+ /** Out: offered on this session, no answer yet. */
70
+ | "offered"
71
+ /** Out: the receiver's person has not decided (or it waits its turn there, `waitingFor: "busy"`). In: this person has not decided. */
72
+ | "asking" | "active" | "paused"
73
+ /** Every byte confirmed; the receiver is checking the digest. */
74
+ | "verifying" | "done" | "failed" | "declined" | "cancelled";
75
+ export interface FileTransferRecord {
76
+ /** The sender's id, on the wire. */
77
+ id: string;
78
+ direction: "in" | "out";
79
+ file: FileInfo;
80
+ state: TransferState;
81
+ /** Out: bytes the receiver confirmed. In: bytes stored durably, where a restart resumes. */
82
+ confirmed: number;
83
+ /** SHA-256 of the file, base64url: the sender's own, or the one it announced. */
84
+ digest?: string;
85
+ pausedBy?: "me" | "peer";
86
+ /** Out, `asking`: why the receiver waits. */
87
+ waitingFor?: "consent" | "busy";
88
+ error?: string;
89
+ /** When the transfer began (the offer), for its time to live. */
90
+ since: number;
91
+ /** In: the person accepted it (not taken on its own). */
92
+ consented?: boolean;
93
+ /**
94
+ * In, `cancelled`: the sender stopped it (`pf-abort`), not this person. Offered again (the sender could not read its
95
+ * file and sends it again), it is taken again from the start.
96
+ */
97
+ abortedBySender?: boolean;
98
+ /**
99
+ * In: taken, by the person or within the app's limits. An offer that expired unanswered never was, so offered again
100
+ * it is refused, never taken without asking.
101
+ */
102
+ agreed?: boolean;
103
+ }
104
+ export declare const transferEnded: (record: FileTransferRecord) => boolean;
105
+ /**
106
+ * Whether an unfinished transfer is stuck, so its person is offered to push it: "Send again" (sending) or "Ask again"
107
+ * (receiving). `movedAt` is when its bytes last moved, `restored` that it has not moved since the app started. What
108
+ * waits for a person (an answer, a pause) is not stuck, and a failed one has its own "Retry".
109
+ */
110
+ export declare function transferStalled(record: FileTransferRecord, movedAt: number, restored: boolean, now: number): boolean;
111
+ /** A file being sent, read in ranges. */
112
+ export interface OutgoingSource {
113
+ read(offset: number, length: number): Promise<Uint8Array>;
114
+ /** SHA-256 of the whole file, base64url. */
115
+ digest(): Promise<string>;
116
+ }
117
+ /** Where a file being received is written, in order, from `offset`. */
118
+ export interface IncomingTarget {
119
+ /** Bytes already stored when it was opened: where this transfer resumes. */
120
+ readonly offset: number;
121
+ append(bytes: Uint8Array): Promise<void>;
122
+ /** What was appended is durable. */
123
+ flush(): Promise<void>;
124
+ /** Checks what was stored against the sender's digest, and keeps the file when it matches. */
125
+ verify(digest: string): Promise<boolean>;
126
+ /** Removes what was stored. */
127
+ discard(): Promise<void>;
128
+ }
129
+ export type OfferDecision = "accept" | "ask" | {
130
+ refuse: RefuseReason;
131
+ room?: number;
132
+ };
133
+ export type RefuseReason = "declined" | "no-room" | "too-many" | "damaged" | "cancelled" | "expired" | "invalid";
134
+ export interface ChatFilesHost {
135
+ /** Sends a frame on the open session; false when there is none. */
136
+ send(frame: Record<string, unknown>): boolean;
137
+ /**
138
+ * A new offer from the contact: take it, ask the person, or refuse it. `again`: a file taken here without asking
139
+ * that ended (failed, or stopped by the sender) and is offered again; it counts against the same limits as a new one.
140
+ */
141
+ decide(file: FileInfo, again?: boolean): Promise<OfferDecision>;
142
+ openTarget(record: FileTransferRecord): Promise<IncomingTarget>;
143
+ openSource(record: FileTransferRecord): Promise<OutgoingSource>;
144
+ /**
145
+ * Something changed: keep it and show it. `transferred` is what moved so far (confirmed by the receiver when
146
+ * sending, stored when receiving); `progress` says only that moved, so keeping it can wait.
147
+ */
148
+ changed(record: FileTransferRecord, transferred: number, progress: boolean): void;
149
+ /** Bytes a file may still take here, or null when the platform does not say. */
150
+ room?(): Promise<number | null>;
151
+ /**
152
+ * Resolves once the session can take another data frame without crowding out everything else on it (nothing when it
153
+ * can now: a large file does not make a promise per frame). Channels with a
154
+ * small send budget (native, iroh) refuse frames past it; sending into a full one again at once spun a loop of
155
+ * promises that never let the budget drain, and froze the app.
156
+ */
157
+ writable?(): Promise<void> | undefined;
158
+ /**
159
+ * Asked before each data frame once a transfer has sent more than its file's size (`sent` is every byte of data sent
160
+ * for it so far, parts sent again included): false ends the transfer. A host with a budget for what it sends says so here.
161
+ */
162
+ resend?(record: FileTransferRecord, sent: number): boolean;
163
+ now?(): number;
164
+ }
165
+ /** What a refusal means to the sender's person. */
166
+ export declare function refusalText(why: string, room?: number): {
167
+ state: TransferState;
168
+ error: string;
169
+ };
170
+ export declare class ChatFiles {
171
+ private readonly host;
172
+ private readonly entries;
173
+ private attached;
174
+ private peerRoomValue;
175
+ constructor(host: ChatFilesHost);
176
+ private now;
177
+ /** Records kept from before a restart. Nothing is sent until `attach`. */
178
+ restore(records: FileTransferRecord[]): void;
179
+ get live(): boolean;
180
+ /** What the contact said it can take, on this session. */
181
+ get peerRoom(): number | null;
182
+ records(): FileTransferRecord[];
183
+ get(direction: "in" | "out", id: string): FileTransferRecord | undefined;
184
+ /** Bytes moved so far: confirmed by the receiver (sending), stored (receiving). */
185
+ transferred(direction: "in" | "out", id: string): number;
186
+ /** Bytes of data sent for a file so far, parts sent again included: what sending it cost, whatever the receiver confirmed. */
187
+ sent(id: string): number;
188
+ private moved;
189
+ private changed;
190
+ private send;
191
+ /** A session that agreed files/3 is open: say what fits here, then offer again what is not finished. */
192
+ attach(): void;
193
+ /** The session went: nothing moves until the next one. What was received is made durable. */
194
+ detach(): void;
195
+ /** Offers ended by their time to live. The host calls it now and then; `attach` does too. */
196
+ sweep(): void;
197
+ private sayRoom;
198
+ /** A new file to send: offered now if a session is open, or on the next one. */
199
+ offer(file: FileInfo, digest?: string): FileTransferRecord;
200
+ private offerFrame;
201
+ private announce;
202
+ private armStall;
203
+ private source;
204
+ private chunkAt;
205
+ private shouldPump;
206
+ /**
207
+ * Whether the next `length` bytes go. Within the file's size they always do; past it the receiver is having parts
208
+ * sent again, which nothing it says bounds, so this side does.
209
+ */
210
+ private mayResend;
211
+ private pump;
212
+ private sendSum;
213
+ private waitingOffers;
214
+ private activeIncoming;
215
+ /**
216
+ * Removes what this side stored of an incoming file that ends here. Through its target, opened now if need be: after
217
+ * a restart a transfer has none until bytes arrive again, and one cancelled before that kept its part on the disk.
218
+ * After the write under way, and with the ones queued behind it stopped: a write landing after the removal would
219
+ * store a part of the file again.
220
+ */
221
+ private discardStored;
222
+ private target;
223
+ /** An accepted file goes when a session is open and fewer than three others arrive at once. */
224
+ private startIncoming;
225
+ /** The next file waiting its turn, once one ends. */
226
+ private startNext;
227
+ private onOffer;
228
+ /**
229
+ * An agreed file that ended here, offered again. One the person consented to is taken again from the start; one taken
230
+ * without asking is decided again, as a new offer would be (the contact's limit for files taken without asking, and
231
+ * the room here): taken again, asked about, or refused. True when it is taken again.
232
+ */
233
+ private retakeAgreed;
234
+ /** An agreed file that ended here, offered again: taken again from the start. */
235
+ private retake;
236
+ private onData;
237
+ /** What was stored is durable, and a restart resumes from there. */
238
+ private checkpoint;
239
+ private checkpointNow;
240
+ /** Nothing arrives for a file under way: after a quiet spell the receiver says again where it stands. */
241
+ private armNudge;
242
+ /** `pf-accept` from what is taken here: the sender goes on from there (it ignores it for a transfer that ended). */
243
+ private askAgain;
244
+ private onSum;
245
+ /** A frame from the contact (one of `FILE_FRAMES`). Returns quickly: writing goes on in the background. */
246
+ handle(frame: Record<string, unknown>): Promise<void>;
247
+ private end;
248
+ private entry;
249
+ /** Takes an offered file. */
250
+ accept(id: string): void;
251
+ decline(id: string): void;
252
+ pause(direction: "in" | "out", id: string): void;
253
+ resume(direction: "in" | "out", id: string): void;
254
+ cancel(direction: "in" | "out", id: string): void;
255
+ /** A sent file that failed, offered again from the start under its id. */
256
+ retry(id: string): void;
257
+ /**
258
+ * "Send again": a sent file that failed, or stopped moving, is offered again now (or on the next session). The
259
+ * receiver answers from what it holds, so it goes on from there, never twice in the chat: same id, same message.
260
+ * True when it went now.
261
+ */
262
+ resend(id: string): boolean;
263
+ /**
264
+ * "Ask again": a file that stopped arriving is asked for again from where it stands here. No new frame: a receiver's
265
+ * `pf-accept` already moves any files/3 sender to its offset.
266
+ * True when it went now.
267
+ */
268
+ request(id: string): boolean;
269
+ /** Forgets a transfer (its message was deleted): an unfinished one is cancelled on both sides first. */
270
+ forget(direction: "in" | "out", id: string): void;
271
+ }
@@ -0,0 +1,72 @@
1
+ /**
2
+ * Whether this device's own clock seems to be off, and by how much, so the app can say so where people look at the
3
+ * connection (the chat's connection panel, Settings → Network): "This device's clock seems to be off by about 2 minutes.
4
+ * Chats may be slow to connect."
5
+ *
6
+ * Ghostly dates what it publishes by this device's clock, and several of its checks hold a contact's dates against
7
+ * it. A clock a few minutes off makes chats and groups slow to connect, or never connect with apps that have not been
8
+ * updated, and nothing on screen says why. The app cannot set the clock; it can notice and say.
9
+ *
10
+ * What it hears (`ClockWatch`), each as "this clock minus theirs is between `low` and `high`":
11
+ * - a **server**: the `Date` header of an HTTP answer (a Pkarr relay's), a time to the second read between the moment
12
+ * the request went out and the moment its answer came. Where a browser may not read that header of another origin,
13
+ * there is none.
14
+ * - a **contact**: the time of a contact's packet that came between two close reads of its record. Its own clock dated
15
+ * it, and this device knows within seconds when it was published.
16
+ *
17
+ * The rule, on purpose slow to say yes, and never on one contact's word (it is as likely that contact's clock):
18
+ * - a source says "off" only when everything it allows is more than `CLOCK_OFF_MS` on one side;
19
+ * - two servers that both say so, the same way, are enough: servers keep time;
20
+ * - else one server and a contact that say so, with no contact saying otherwise;
21
+ * - else three contacts that say so, the same way, and at least three for each one that does not.
22
+ * The amount is the middle of what the sources that say so give (the servers', when two do). Evidence older than
23
+ * `CLOCK_EVIDENCE_MS` says nothing: a clock that was set right is believed at the next answer, and the note goes away.
24
+ */
25
+ /** A clock closer than this to the others' is not said to be off: a minute is what apps up to 1.0.2 allow at their strictest. */
26
+ export declare const CLOCK_OFF_MS = 60000;
27
+ /** Evidence older than this says nothing about the clock now. */
28
+ export declare const CLOCK_EVIDENCE_MS: number;
29
+ /** Contacts that must say so when no server does. */
30
+ export declare const CLOCK_PEERS = 3;
31
+ /** Servers that are enough by themselves. */
32
+ export declare const CLOCK_SERVERS = 2;
33
+ /** A contact's packet says something only when the two reads around it were this close. */
34
+ export declare const CLOCK_PEER_READ_GAP_MS = 15000;
35
+ export interface ClockSample {
36
+ low: number;
37
+ high: number;
38
+ at: number;
39
+ }
40
+ /**
41
+ * The rule alone: how far this clock is from the others' (ms, positive when it is ahead) when the samples fresh at
42
+ * `now` say it is clearly off, else null.
43
+ */
44
+ export declare function clockOffset(servers: ReadonlyMap<string, ClockSample>, peers: ReadonlyMap<string, ClockSample>, now: number): number | null;
45
+ export declare class ClockWatch {
46
+ private readonly onChange;
47
+ private readonly now;
48
+ private readonly servers;
49
+ private readonly peers;
50
+ private was;
51
+ private timer;
52
+ /** `onChange`: what `offset` says changed (it appeared, went away, or moved by a minute). */
53
+ constructor(onChange?: (offset: number | null) => void, now?: () => number);
54
+ /**
55
+ * A server's time: `date` (ms, to the second) from an answer to a request that went out at `sent` and came back at
56
+ * `received`, both by this clock.
57
+ */
58
+ server(source: string, date: number, sent: number, received: number): void;
59
+ /**
60
+ * A contact's packet, dated `packetAt` by its clock, that came between this device's reads of its record at
61
+ * `readBefore` and `readAt` (this clock). Says nothing when the two reads were far apart.
62
+ */
63
+ peer(peer: string, packetAt: number, readBefore: number, readAt: number): void;
64
+ private keep;
65
+ /** This clock minus the others', in ms (positive: ahead), when it is clearly off; else null. */
66
+ get offset(): number | null;
67
+ /** The clock was set, or the evidence is of another time: nothing is known until the next answers. */
68
+ reset(): void;
69
+ /** Stops the timer that lets the evidence age out. */
70
+ close(): void;
71
+ private settle;
72
+ }