@ghostlytools/sdk 1.3.10 → 1.4.0

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 (39) hide show
  1. package/dist/app.js +19 -4
  2. package/dist/app.js.map +1 -1
  3. package/dist/core.js +2 -2
  4. package/dist/{fakes-DRPAYl6q.js → fakes-DkFOiAo6.js} +2 -2
  5. package/dist/{fakes-DRPAYl6q.js.map → fakes-DkFOiAo6.js.map} +1 -1
  6. package/dist/fakes.js +1 -1
  7. package/dist/index.js +2 -2
  8. package/dist/{keet-identity-key-D-FT8FmL.js → keet-identity-key-CZ27HbZq.js} +2 -2
  9. package/dist/{keet-identity-key-D-FT8FmL.js.map → keet-identity-key-CZ27HbZq.js.map} +1 -1
  10. package/dist/{src-DFY7sUQ4.js → src-BBoCvzFt.js} +28665 -26743
  11. package/dist/src-BBoCvzFt.js.map +1 -0
  12. package/dist/testing.js +3 -3
  13. package/dist/types/core/src/appBundle.d.ts +4 -3
  14. package/dist/types/core/src/chatFiles.d.ts +32 -2
  15. package/dist/types/core/src/contactInbox.d.ts +68 -0
  16. package/dist/types/core/src/contactLink.d.ts +27 -0
  17. package/dist/types/core/src/contactRecords.d.ts +87 -0
  18. package/dist/types/core/src/dhtDelivery.d.ts +17 -0
  19. package/dist/types/core/src/ghostlink.d.ts +34 -3
  20. package/dist/types/core/src/groupCommunity.d.ts +35 -3
  21. package/dist/types/core/src/groupFiles.d.ts +5 -5
  22. package/dist/types/core/src/groupMeta.d.ts +19 -0
  23. package/dist/types/core/src/groupSession.d.ts +47 -5
  24. package/dist/types/core/src/groupSignals.d.ts +12 -1
  25. package/dist/types/core/src/index.d.ts +7 -0
  26. package/dist/types/core/src/link.d.ts +22 -2
  27. package/dist/types/core/src/miniApp.d.ts +56 -6
  28. package/dist/types/core/src/pairedCalls.d.ts +8 -3
  29. package/dist/types/core/src/pairedHttp.d.ts +9 -1
  30. package/dist/types/core/src/relay.d.ts +71 -6
  31. package/dist/types/core/src/transport.d.ts +21 -0
  32. package/dist/types/core/src/x401.d.ts +140 -0
  33. package/dist/types/core/src/x401Credential.d.ts +58 -0
  34. package/dist/types/core/src/x401Presentation.d.ts +96 -0
  35. package/dist/types/core/src/x401Request.d.ts +79 -0
  36. package/dist/{verify-sFNwqV7P.js → verify-BWtbTAs7.js} +2 -2
  37. package/dist/{verify-sFNwqV7P.js.map → verify-BWtbTAs7.js.map} +1 -1
  38. package/package.json +3 -3
  39. package/dist/src-DFY7sUQ4.js.map +0 -1
@@ -278,6 +278,8 @@ export interface GroupState {
278
278
  nicks: Record<string, string>;
279
279
  /** The group's metadata (its picture), as the admin last signed it and I accepted it. */
280
280
  meta?: GroupMeta;
281
+ /** A few statements I held before `meta`, oldest first, for a member back from away (`keepPastGroupMeta`). Absent in older states. */
282
+ metaPast?: GroupMeta[];
281
283
  /**
282
284
  * My frames no edge took when I said them, as `e:n`, oldest first, kept until each was looked at once for saying again
283
285
  * (`resealBehind`): I may have been behind on the chain without knowing. Absent in older states.
@@ -289,6 +291,9 @@ export interface GroupState {
289
291
  /**
290
292
  * `completes`: this message was delivered before from a copy another member handed on without its author's whole
291
293
  * signature (its text only); this is the whole one, with the mentions, reply and hop count its author put there.
294
+ * `live`: it came straight from its author, over the author's own edge, as it was written: not handed on by another
295
+ * member, not an answer to my sync (a catch-up) and not one that waited for a secret. How long it took says how far
296
+ * the author's clock is from mine.
292
297
  */
293
298
  /**
294
299
  * `frame`: the frame the message came in, as it is kept to hand on to a member who missed it (only its author's own
@@ -308,6 +313,7 @@ export interface GroupIncomingMessage {
308
313
  file?: GroupFileMeta;
309
314
  completes?: true;
310
315
  frame?: GroupMessageFrame;
316
+ live?: true;
311
317
  }
312
318
  export interface GroupSessionHooks {
313
319
  save(state: GroupState): Promise<void>;
@@ -424,8 +430,25 @@ export declare class GroupSession {
424
430
  * before revision 2026-10-13, and never marks them seen) is not handed them again at every sync. In memory only.
425
431
  */
426
432
  private leaversHanded;
433
+ /**
434
+ * The frames a commit took out of the logs (`pruneRelay`), newest last, and whether the app holds them with its
435
+ * messages: a removal's `left` mark can come after its commit, and what the leaver wrote is then kept again
436
+ * (`unprune`). In memory only: started again, the app's rows bring theirs back.
437
+ */
438
+ private pruned;
427
439
  /** Syncs answered per member, a few a minute (`GROUP_LIMITS.syncAnswers`). In memory only. */
428
440
  private syncsAnswered;
441
+ /**
442
+ * Per author and epoch, the highest number another member's sync says it has (`have`), for the epochs I was in and
443
+ * of which I hold nothing at all (`hear`): what `lacking` names, so another member is asked for it. Only a member's
444
+ * word, so it never counts as seen. In memory only: the syncs come again when the edges do.
445
+ */
446
+ private heard;
447
+ /**
448
+ * Per member: until when what comes over its edge may be its answer to my sync (`syncFrame`), a catch-up and not a
449
+ * message written just now. Each frame of the answer keeps it open: it goes a slice at a time. In memory only.
450
+ */
451
+ private readonly answering;
429
452
  /** Catch-up answers still going out, a slice at a time (`handOut`). */
430
453
  private readonly answers;
431
454
  /**
@@ -485,6 +508,7 @@ export declare class GroupSession {
485
508
  private policyOf;
486
509
  /** The current epoch's rendezvous secret (its beacon and lobbies), once its secret is here. */
487
510
  get rendezvous(): string | undefined;
511
+ private now;
488
512
  /** Epochs whose messages this member can still read. */
489
513
  get readableEpochs(): number[];
490
514
  /**
@@ -506,8 +530,19 @@ export declare class GroupSession {
506
530
  * is for another member to hand on.
507
531
  */
508
532
  lacking(): Map<string, string>;
509
- /** What a sync names in `miss` for one sender now: per epoch, the newest `GROUP_LIMITS.miss` numbers that never arrived. */
533
+ /**
534
+ * What a sync names in `miss` for one sender now: per epoch, the newest `GROUP_LIMITS.miss` numbers that never arrived.
535
+ * And, for an epoch of which none arrived, the newest numbers another member said it has (`heard`): a member back
536
+ * after someone joined, whose author wrote 32 since (all its own answer holds), had nothing below them to ask for.
537
+ */
510
538
  missOf(sender: string): Record<string, number[]>;
539
+ /**
540
+ * Whether `member` may hold some of what never reached me from `sender` (`missOf`): it was in one of those epochs.
541
+ * One let in since was not, and a member asks it for them in vain.
542
+ */
543
+ mayHold(member: string, sender: string): boolean;
544
+ /** What another member's sync says it has of the epochs I was in, can read, and hold nothing of (`heard`). */
545
+ private hear;
511
546
  /** Whether any of `asked` (per epoch, as `missOf` gave them) arrived since: the member asked holds what is missing. */
512
547
  filledSince(sender: string, asked: Record<string, number[]>): boolean;
513
548
  private serialize;
@@ -549,6 +584,8 @@ export declare class GroupSession {
549
584
  * epochs before its leave (WISP 902 § Catch-up).
550
585
  */
551
586
  private pruneRelay;
587
+ /** The frames `pruneRelay` dropped that are handed on again now (a removal's `left` mark came after it), back in their logs. */
588
+ private unprune;
552
589
  /** Another member's edit, kept to hand on: the latest per message; the oldest go once the log is full. False: one as new was kept. */
553
590
  private keepEdit;
554
591
  /** A frame of another member, kept to hand on; the oldest go once the log is full. */
@@ -636,9 +673,10 @@ export declare class GroupSession {
636
673
  }>;
637
674
  /**
638
675
  * What to tell a member whose edge just opened: where I am, what I have from everyone and what never arrived below
639
- * that. `ask`: the members whose messages I want this one to hand on, since their own edges to me are down.
676
+ * that. `ask`: the members whose messages I want this one to hand on, since their own edges to me are down. `to`: the
677
+ * member it goes to, whose frames for a while may be its answer, a catch-up (never `live`).
640
678
  */
641
- syncFrame(ask?: readonly string[]): GroupSyncFrame;
679
+ syncFrame(ask?: readonly string[], to?: string): GroupSyncFrame;
642
680
  /** Sequence numbers below the highest seen that never arrived, the newest `miss` of them. */
643
681
  private gaps;
644
682
  setNick(key: string, nick: string | undefined): Promise<void>;
@@ -711,7 +749,9 @@ export declare class GroupSession {
711
749
  * The author's name in a message (`nk`), when the author's signature over it (`ns`) holds: any copy, handed on or
712
750
  * not, whole or not, since a member handing it on can only drop it. Taken only from a message newer than the one it
713
751
  * last came in, or than the moment an edge last said it (`setNick`), so a catch-up's older pages never bring back a
714
- * name the member changed since. Whether the name I hold changed.
752
+ * name the member changed since. The name I hold already costs no signature check: a box sealed by a member handing
753
+ * the frame on can only say that name again, at a time under the author's `sig`, and at most hold back an older page's
754
+ * newer name until the author's next message, as withholding those pages would. Whether the name I hold changed.
715
755
  */
716
756
  private heardName;
717
757
  private openMentions;
@@ -730,7 +770,8 @@ export declare class GroupSession {
730
770
  private receiveCommit;
731
771
  /**
732
772
  * Whether a frame of `author` under `epoch` is taken from another member, kept and handed on: while its author is in
733
- * the roster, or when it left (its removal marked `left`, and it is not back in) and the frame is from before that.
773
+ * the roster, or when it left (its removal marked `left`, and it is not back in) and the frame is from before that,
774
+ * and from after any removal of it before that was not a leave: let back in, it is not handed on for those epochs.
734
775
  */
735
776
  private handsOn;
736
777
  /** Keeps the admin's mark on a commit that took out a member who left (`GroupCommitFrame.left`) when it holds; true when new. */
@@ -764,6 +805,7 @@ export declare class GroupSession {
764
805
  private publishMeta;
765
806
  /** My statement, to a member whose sync says it holds an older one (or none); nothing to an app that says nothing. */
766
807
  private offerMeta;
808
+ /** The statements a member whose sync says it holds `theirTag` missed, oldest first, sealed under my current epoch (`groupMetaToHand`). */
767
809
  private metaFor;
768
810
  /**
769
811
  * A metadata statement: kept when it is newer than mine, its commit is on my chain, its signer was
@@ -85,6 +85,12 @@ export interface CarriedHooks {
85
85
  direct?(payload: Uint8Array): boolean;
86
86
  /** `CARRIED_DEFER_MS`, for tests. */
87
87
  deferMs?: number;
88
+ /**
89
+ * The date of the last packet an earlier transport of this edge signed (`lastDated`), before the edge started again:
90
+ * mine are dated past it. Dated by the clock alone, the first packet of an edge started again in the same millisecond
91
+ * (its WebRTC gave up, `edgeWithoutRtc`) was no newer than the last one, and a relay refused it (409).
92
+ */
93
+ after?: bigint;
88
94
  }
89
95
  /**
90
96
  * The Pkarr transport of one edge, with members carrying its packets beside the relays. Publishes under the edge's own
@@ -129,8 +135,13 @@ export declare class CarriedTransport implements PkarrTransport {
129
135
  relays: string[];
130
136
  };
131
137
  publish(identity: Identity, records: GhostRecord[], options?: PkarrRequestOptions): Promise<void>;
132
- /** My next packet for this edge, signed and dated: each newer than the last, as the relays' copy keeps them. */
138
+ /**
139
+ * My next packet for this edge, signed and dated: each newer than the last, as the relays' copy keeps them, and past
140
+ * `after` (what a relay that refused one holds).
141
+ */
133
142
  private stamp;
143
+ /** The date of the last packet this transport signed (0 for none): an edge started again dates its own past it. */
144
+ lastDated(): bigint;
134
145
  /**
135
146
  * The relays get the very packet members carried or the edge itself handed over, byte for byte, where the transport
136
147
  * can put a payload signed here: a copy dated again by the relays' transport was a packet the member had not seen,
@@ -14,6 +14,9 @@ export * from "./deviceLink.js";
14
14
  export * from "./relayBreaker.js";
15
15
  export * from "./invite.js";
16
16
  export * from "./deviceInvite.js";
17
+ export * from "./contactLink.js";
18
+ export * from "./contactRecords.js";
19
+ export * from "./contactInbox.js";
17
20
  export * from "./enroll.js";
18
21
  export * from "./setUpdate.js";
19
22
  export * from "./handoff.js";
@@ -98,3 +101,7 @@ export * from "./appStatements.js";
98
101
  export * from "./appBundle.js";
99
102
  export * from "./appStore.js";
100
103
  export * from "./appUpdates.js";
104
+ export * from "./x401.js";
105
+ export * from "./x401Credential.js";
106
+ export * from "./x401Presentation.js";
107
+ export * from "./x401Request.js";
@@ -74,8 +74,21 @@ export declare const AWAITING_PEER_MS: number;
74
74
  * to invites nobody may ever open, and a join on one was noticed 90 s later (bug hunt 1013-1642, 2026-10-13).
75
75
  */
76
76
  export declare const UNUSED_INVITE_WAIT_MAX_MS: number;
77
- /** The wait between reads of an unused invite of age `age` (`UNUSED_INVITE_WAIT_MAX_MS`), never shorter than the pace's `interval`. */
78
- export declare function unusedInviteWait(age: number, interval: number): number;
77
+ /**
78
+ * The reads a minute the unused invites of an app (their keys and their mailboxes) take between them, half the relays'
79
+ * background share: the slower reads stretch only as far as their count needs. Slowed whatever the count, a single
80
+ * invite opened 20 minutes later was noticed 136 s after the join, where the background pace takes 30 s at most (bug
81
+ * hunt 1014-0136, 2026-10-14).
82
+ */
83
+ export declare const UNUSED_INVITE_READS_PER_MINUTE = 10;
84
+ /** Counts `reader` (an invite's key or mailbox) among the unused ones read over `transport` while `unused`, or no longer: how many there are. */
85
+ export declare function countUnusedInvite(transport: PkarrTransport, reader: object, unused: boolean): number;
86
+ /**
87
+ * The wait between reads of an unused invite of age `age`, one of `readers` read over the same relays: a fifth of its
88
+ * age, up to `UNUSED_INVITE_WAIT_MAX_MS`, but no longer than their count needs (`UNUSED_INVITE_READS_PER_MINUTE`), and
89
+ * never shorter than the pace's `interval`.
90
+ */
91
+ export declare function unusedInviteWait(age: number, interval: number, readers: number): number;
79
92
  /**
80
93
  * A group link's peer whose packet advertises and carries no `_tr` on every read for this long publishes none: what it
81
94
  * said before is forgotten (WISP 902 § Transports). Not at the first such packet: an app with no WebRTC (a Linux
@@ -170,6 +183,11 @@ export interface LinkSessionOptions {
170
183
  * `FIRST_PUBLISH_MAX_MS`.
171
184
  */
172
185
  firstPublish?: "at-start" | "after-first-poll";
186
+ /**
187
+ * Back after a restart with the contact live when this app last ran (`GhostLinkOptions.resume`): its reads say so
188
+ * (`PkarrRequestOptions.resume`) until one is answered.
189
+ */
190
+ resumed?: boolean;
173
191
  /**
174
192
  * When the chat was made, for a saved one: the wait for a peer never seen (`AWAITING_PEER_MS`) counts from then, not
175
193
  * from this start. Counted from each start of the app, every saved chat whose contact had no packet at the relays
@@ -248,6 +266,8 @@ export declare class LinkSession {
248
266
  private readonly firstPublish;
249
267
  private firstPublishTimer;
250
268
  private firstPollDone;
269
+ /** Back after a restart, and no read of the contact answered yet in this run (`LinkSessionOptions.resumed`). */
270
+ private resumeReads;
251
271
  /** When this side last published (0: never). */
252
272
  lastPublishedAt: number;
253
273
  /** A publish is in flight, or finished this recently: another packet now would only queue behind it at the relays. */
@@ -34,6 +34,27 @@ export type MiniAppPeerEvent = {
34
34
  } | {
35
35
  open: false;
36
36
  };
37
+ /**
38
+ * A file the person picked for the app (WISP 1200 · Linked files): the client keeps a link to it, never a copy, and the
39
+ * app reads it by `id`, which the client chose. `path` is relative to what was picked, the picked folder's name first,
40
+ * never where it is on the device.
41
+ */
42
+ export interface MiniAppLinkedFile {
43
+ /** 22 base64url characters. */
44
+ id: string;
45
+ path: string;
46
+ /** Bytes, and when it last changed (ms), as when it was picked. */
47
+ size: number;
48
+ modified: number;
49
+ /** Whether the client can read it now: false after a restart where the browser must be asked again, or before. */
50
+ available: boolean;
51
+ }
52
+ /** `ghostly.files.pick`: a folder (with everything under it) or files, of these extensions only when `accept` names some. */
53
+ export interface MiniAppPickOptions {
54
+ folder?: boolean;
55
+ /** Extensions without the dot, lower case, at most `MINI_APP_LIMITS.filesAccept`. */
56
+ accept?: string[];
57
+ }
37
58
  /** `window.ghostly` inside the sandbox. */
38
59
  export interface MiniAppApi {
39
60
  context(): Promise<MiniAppContext>;
@@ -54,11 +75,28 @@ export interface MiniAppApi {
54
75
  on(event: "message", listener: (data: MiniAppJson) => void): () => void;
55
76
  on(event: "peer", listener: (peer: MiniAppPeerEvent) => void): () => void;
56
77
  };
78
+ /**
79
+ * Files the person picks (the `files` permission): absent in a client that has none, so an app tests for it. The
80
+ * client asks the person and shows its own picker; the app reads only what was picked, by id.
81
+ */
82
+ files?: {
83
+ /** The entries picked now; refused with `cancelled` when the person picks nothing. */
84
+ pick(options?: MiniAppPickOptions): Promise<MiniAppLinkedFile[]>;
85
+ /** Every entry this app keeps. */
86
+ list(): Promise<MiniAppLinkedFile[]>;
87
+ /** At most `MINI_APP_LIMITS.filesReadBytes` from `offset`; fewer at the end of the file. */
88
+ read(id: string, range: {
89
+ offset: number;
90
+ length: number;
91
+ }): Promise<ArrayBuffer>;
92
+ /** Drops one link, or every link with "all". The file itself is never touched. */
93
+ forget(id: string): Promise<void>;
94
+ };
57
95
  /** Ends the app. */
58
96
  close(): Promise<void>;
59
97
  }
60
98
  /** The message types on the port (web, extension) or through `app_broker` (Desktop). */
61
- export type MiniAppRequestType = "context" | "file" | "storage.get" | "storage.set" | "storage.delete" | "storage.keys" | "chat.send" | "close";
99
+ export type MiniAppRequestType = "context" | "file" | "storage.get" | "storage.set" | "storage.delete" | "storage.keys" | "chat.send" | "files.pick" | "files.list" | "files.read" | "files.forget" | "close";
62
100
  /** A request from the app: `{id, type, args}`. The broker refuses an unknown `type`. */
63
101
  export interface MiniAppRequest {
64
102
  id: number;
@@ -73,12 +111,17 @@ export interface MiniAppRequest {
73
111
  *
74
112
  * - `bad-key`: a storage key that is not a string of 1 to 256 bytes.
75
113
  * - `bad-path`: a `file` path that is not a string of 1 to 1024 characters.
76
- * - `bad-request`: a request that is not `{id, type, args}` with JSON arguments.
114
+ * - `bad-request`: a request that is not `{id, type, args}` with JSON arguments, or whose arguments are not the call's.
115
+ * - `cancelled`: `files.pick` that the person closed without picking anything.
116
+ * - `changed`: `files.read` of a file whose size or date changed since it was picked: it is picked again to be read.
77
117
  * - `failed`: anything else; the client's own words never reach the app.
78
118
  * - `full`: a storage write would take the scope past 5 MiB (each key counts 128 bytes, its own bytes eight times and
79
119
  * its value's), so the app can make room.
120
+ * - `gone`: `files.read` of a file that is no longer there, or that the client cannot read now (`available` false), or
121
+ * of an id it does not keep.
80
122
  * - `no-file`: the bundle has no such file.
81
- * - `not-allowed`: `chat.send` without the `chat` permission, or with the app opened alone.
123
+ * - `not-allowed`: `chat.send` without the `chat` permission, or with the app opened alone; `files.*` without the
124
+ * `files` permission, or in a client that cannot keep links.
82
125
  * - `not-open`: `chat.send` before this side's chat has the app open.
83
126
  * - `offline`: `chat.send` while the chat's session is not live. Nothing is kept to send later.
84
127
  * - `peer-closed`: `chat.send` while the contact has not opened the app (or its client does not offer `apps/1`).
@@ -90,7 +133,7 @@ export interface MiniAppRequest {
90
133
  *
91
134
  * A later client may add a code: treat one you do not know as `failed`.
92
135
  */
93
- export declare const MINI_APP_ERROR_CODES: readonly ["bad-key", "bad-path", "bad-request", "failed", "full", "no-file", "not-allowed", "not-open", "offline", "peer-closed", "stopped", "too-fast", "too-large", "unknown-type"];
136
+ export declare const MINI_APP_ERROR_CODES: readonly ["bad-key", "bad-path", "bad-request", "cancelled", "changed", "failed", "full", "gone", "no-file", "not-allowed", "not-open", "offline", "peer-closed", "stopped", "too-fast", "too-large", "unknown-type"];
94
137
  export type MiniAppErrorCode = typeof MINI_APP_ERROR_CODES[number];
95
138
  /** The code of a refused `ghostly.*` call (the rejection's `Error`), or null for anything that is not one. */
96
139
  export declare function miniAppErrorCode(error: unknown): MiniAppErrorCode | null;
@@ -130,10 +173,17 @@ export declare const MINI_APP_LIMITS: {
130
173
  /** Requests per second, per app. */
131
174
  readonly requestsPerSecond: 50;
132
175
  /**
133
- * Bytes of `file` answers per second, per app: a whole bundle's worth. A read that starts under it is answered whole;
134
- * past it `file` is refused with `too-fast` until the second has gone.
176
+ * Bytes of `file`, `files.read` and `files.list` answers per second, per app, counted together: a whole bundle's
177
+ * worth. A request that starts under it is answered whole; past it the request is refused with `too-fast` until the
178
+ * second has gone.
135
179
  */
136
180
  readonly fileBytesPerSecond: number;
181
+ /** One `files.read`, at most. */
182
+ readonly filesReadBytes: number;
183
+ /** The links an app keeps, at most: a pick that would pass it is refused with `too-large`. */
184
+ readonly filesEntries: 100000;
185
+ /** Extensions a `files.pick` may name in `accept`, each 1 to 16 characters of `a-z` and `0-9`. */
186
+ readonly filesAccept: 32;
137
187
  /** A storage key, UTF-8. */
138
188
  readonly storageKeyBytes: 256;
139
189
  /** One stored JSON value, serialized. */
@@ -50,10 +50,15 @@ export declare class PairedCalls {
50
50
  get on(): boolean;
51
51
  /**
52
52
  * This app is going away: a call it placed or answered is hung up, as its person would (its latest signal an
53
- * offer, an answer, or a picture change, which only a call on sends). Returns the hang-up to send before the
54
- * goodbye, or null when no call of ours is on. Read by its kind, not its age: a call outlasts its offer's freshness.
53
+ * offer, an answer, or a picture change, which only a call on sends). `declineRinging` (the app quits: the Desktop app
54
+ * or a CLI daemon) also declines the contact's call still ringing here, so the caller stops ringing for nobody; a web
55
+ * page that goes (a reload looks the same as a close) leaves it ringing, so the reopened page rings again. Returns
56
+ * the hang-up to send before the goodbye, or null when no call is on. Our own call is read by its kind, not its age:
57
+ * a call outlasts its offer's freshness.
55
58
  */
56
- hangUp(): PairedCallFrame | null;
59
+ hangUp(options?: {
60
+ declineRinging?: boolean;
61
+ }): PairedCallFrame | null;
57
62
  /** On a new session that carries calls: the latest signal again, if it is still fresh enough to act on. */
58
63
  pending(): PairedCallFrame | null;
59
64
  }
@@ -1,5 +1,13 @@
1
1
  import { type FrameChannel } from "./frames.js";
2
2
  import { HttpClient, HttpHost, type HostedHttpService, type LocalFetch } from "./http.js";
3
+ /**
4
+ * What the session hears of the bodies going on its channel: each chunk written, with its frame's length, and each wait
5
+ * for room. An app's data in the chat keeps its own share above them, as beside a file (WISP 1200 § In a chat).
6
+ */
7
+ export interface PairedHttpBodies {
8
+ wrote(bytes: number): void;
9
+ waiting(drained: Promise<void>): Promise<void>;
10
+ }
3
11
  /**
4
12
  * Shared services over a paired session: the same HTTP frames as the older data link, carried as
5
13
  * `ph` application frames on the authenticated channel. Binary chunks travel base64url-encoded,
@@ -8,7 +16,7 @@ import { HttpClient, HttpHost, type HostedHttpService, type LocalFetch } from ".
8
16
  export declare class PairedHttp {
9
17
  readonly client: HttpClient;
10
18
  readonly host: HttpHost;
11
- constructor(channel: FrameChannel, getService: (id: string) => HostedHttpService | undefined, localFetch: LocalFetch);
19
+ constructor(channel: FrameChannel, getService: (id: string) => HostedHttpService | undefined, localFetch: LocalFetch, bodies?: PairedHttpBodies);
12
20
  /** One `ph` frame from the peer. Anything that is not HTTP traffic is ignored. */
13
21
  handle(frame: Record<string, unknown>): void;
14
22
  close(): void;
@@ -93,8 +93,38 @@ export declare const DEPARTED_READS = 6;
93
93
  * groups'. A private group's admin that had just let members in and seen them restart had spent its minute in 30 s;
94
94
  * a member back then, with no other member online to carry its offer, had it read only when the minute freed: 18 to
95
95
  * 42 s later, one round in four of the member-back runs (2026-10-03).
96
+ *
97
+ * It is also theirs whatever the chats do: while the edges' signaling has had fewer than that many requests on a relay
98
+ * in the last minute, neither the limit, nor the chats' own allowance past it, nor their reserve (`CHAT_RESERVE`) holds
99
+ * it back. Its reads leave the last of it to a write there too. A daemon with 30 chats and 5 groups, back after a
100
+ * restart, had its chats signal for 332 s: they kept their reserve, their allowance took what the limit left, and the
101
+ * edges got nothing. By then their attempts had failed and backed off, and the group members were reachable again 13
102
+ * to 25 min after the restart (CLI bug hunt, 2026-10-08).
103
+ *
104
+ * An edge back after a restart reads its member before it offers (`resume`), and those reads are on the floor too: as
105
+ * plain reads, they waited behind the chats as before, and the edges never got to signal. The same daemon had its first
106
+ * member back 71 to 367 s after the restart, and group texts sent in its first minutes were read 2 to 7 min late (CLI
107
+ * bug hunt, 2026-10-14).
96
108
  */
97
109
  export declare const GROUP_SIGNALING_ALLOWANCE_SHARE: number;
110
+ /**
111
+ * A community member's way back to its group while it has no edge up (its readings of the beacon, its request in a hub's
112
+ * lobby: `back`) may go past everything that holds a group's request back by this fraction of a relay's minute (6 on a
113
+ * relay of 30, 12 on one of 60, 1 on a relay of 5), its own: not the edges' (`GROUP_SIGNALING_ALLOWANCE_SHARE`),
114
+ * and what it takes counts there alone, so it shortens no one else's minute or allowance. Its reads leave the last of it
115
+ * to a write. A web app opened with 30 chats whose contacts were online and 15 groups whose edges all offered at once:
116
+ * the edges' offers and reads for their members spent the groups' allowance in its first second, the chats' reserve
117
+ * and their offers still waiting held the rest, and its 5 communities read their beacon (who the hubs are) a minute
118
+ * later, or not in 3 minutes; 2 of them were not back in 6 (bug hunt, 2026-10-14). Sized for 5 communities' way back
119
+ * in the first minute on the default relays: a reading of each beacon, and a read and a write in a hub's lobby (a write
120
+ * goes to every relay). A member asks it only while it has no edge up in that community.
121
+ *
122
+ * At worst a relay then sees, in one minute, its limit, the chats' allowance past it, the edges' and this one: 46 on a
123
+ * relay of 30 (pkarr.pubky.org allows 50 an address, `x-ratelimit-limit`), 92 on pkarr.pubky.app's 60 (it allows 1000)
124
+ * and 7 on a relay of 5 (relay.pkarr.org and pkarr.miguelmedeiros.dev allow 10). A share raised past those limits gets
125
+ * 429s (docs/TRANSPORTS.md, "The default list").
126
+ */
127
+ export declare const WAY_BACK_SHARE: number;
98
128
  /** Past the limit, a group's reads within its allowance go no more often than this on a relay. */
99
129
  export declare const GROUP_OVER_PACE_MS = 5000;
100
130
  /**
@@ -116,6 +146,16 @@ export declare const GROUP_BURST_ONE_LINK = 8;
116
146
  * read only when the minute freed, 25 to 44 s on, and its edge came up then (bug hunt r12, measured again 2026-10-03).
117
147
  */
118
148
  export declare const WATCH_SHARE: number;
149
+ /**
150
+ * 1:1 chats' reads of contacts that went away from a live session and have not shown themselves back (`watch`) take at
151
+ * most this share of a relay's requests the same way, on their own (a chat never waits behind the edges that watch the
152
+ * same contact): 3 in any 10 s on a relay of 30, more than one contact's fast poll asks for. The key read longest ago
153
+ * goes first. Not the few reads of a contact that just went away past the limit (`DEPARTED_READS`). Ten contacts that
154
+ * left a CLI daemon at once were read every 2 s each: those reads spent both relays' minute in the 10 s after their
155
+ * goodbyes, when none could be back yet, then the daemon read nobody, nor answered anyone, for 45 s, and the chats with
156
+ * no HyperDHT listener at the daemon were live again 42 to 51 s after their contacts were back (CLI bug hunt, 2026-10-14).
157
+ */
158
+ export declare const CHAT_WATCH_SHARE: number;
119
159
  /**
120
160
  * Once a group's read found a relay's minute full, the groups' reads there are spread over the minute for a minute
121
161
  * (`GROUP_RATION_MS`): at most a sixth of it in any 10 s (5 on a relay of 30), the key read longest ago first. A sliding
@@ -229,13 +269,20 @@ export declare class RelayTransport implements PkarrTransport {
229
269
  private readonly spentGroupUrgent;
230
270
  /** Watch reads on each relay in the last `GROUP_RATION_WINDOW_MS` (`WATCH_SHARE`). */
231
271
  private readonly spentWatch;
272
+ /** 1:1 chats' watch reads on each relay in the last `GROUP_RATION_WINDOW_MS` (`CHAT_WATCH_SHARE`). */
273
+ private readonly spentChatWatch;
232
274
  /** Groups' reads past the limit on each relay in the last `GROUP_OVER_PACE_MS` (`GROUP_SIGNALING_ALLOWANCE_SHARE`). */
233
275
  private readonly spentGroupOver;
276
+ /** Group edges' signaling requests on each relay in the last minute: their floor (`GROUP_SIGNALING_ALLOWANCE_SHARE`). */
277
+ private readonly spentGroupSignal;
278
+ /** Community members' ways back on each relay in the last minute: their allowance (`WAY_BACK_SHARE`). */
279
+ private readonly spentWayBack;
234
280
  /** Per contact, its departed reads past the limit in the last minute, every relay together (`DEPARTED_READS`). */
235
281
  private readonly departedOver;
236
282
  /**
237
283
  * Per key a group reads (not in the background), when a read of it last went out and when it last asked: whose turn
238
- * it is under the watch share (`WATCH_SHARE`) and while the groups' reads are rationed (`GROUP_RATION_WINDOW_MS`).
284
+ * it is under the watch share (`WATCH_SHARE`) and while the groups' reads are rationed (`GROUP_RATION_WINDOW_MS`). And
285
+ * per key a chat watches, whose turn it is under theirs (`CHAT_WATCH_SHARE`).
239
286
  */
240
287
  private readonly readTurns;
241
288
  /** Per key read in turn (`isTurnRead`), when a read of it last went out and when it last asked (`READ_TURN_MS`). */
@@ -342,6 +389,15 @@ export declare class RelayTransport implements PkarrTransport {
342
389
  * (`signedAt`) and is not checked again. `conflict`: as `publishDated` gives it.
343
390
  */
344
391
  publishPayload(pubKeyZ32: string, payload: Uint8Array, options?: PkarrRequestOptions, conflict?: (relay: string) => void): Promise<void>;
392
+ /**
393
+ * A payload signed in this process (a group edge's offer or answer, `CarriedTransport`) put on every relay, past what
394
+ * a relay that answers 409 holds: that one is read, and the records go again at once, signed by `options.redate` dated
395
+ * just past it, `left` times at most. A packet put here is the key's latest too: a publish dated here next
396
+ * (`nextTimestamp`, the goodbye after the edge stops) goes past it. Before, the 409 failed the publish (or, when another
397
+ * relay took it, left the relay's copy in place), the link tried again 4 s on with its clock's date, refused as long as
398
+ * the relay's copy was later, and an edge started again in the same millisecond lost its new offer to its last one.
399
+ */
400
+ private putRedated;
345
401
  /**
346
402
  * Puts the packet on every relay and settles as soon as one of them took it. A relay that is slow to
347
403
  * answer (one that stores the packet and answers the PUT only at the timeout) must not hold a link's
@@ -397,13 +453,15 @@ export declare class RelayTransport implements PkarrTransport {
397
453
  private readFrom;
398
454
  /**
399
455
  * A relay whose budget (this client's, or its own rate limit) held a packet back that another relay took: it gets
400
- * that packet when it frees a request, as a background write. Only the newest per key and relay; a newer packet put
401
- * everywhere drops it. Without this, that relay kept the key's older packet for good, and an app that restarted and
402
- * read it first found a contact's offer long answered, answered it again, and waited on it (bug hunt r7a).
456
+ * that packet when it frees a request, as a background write (`who`: a group edge's offer or answer as its own, also
457
+ * after that relay failed it). Only the newest per key and relay; a newer packet put everywhere drops it. Without this,
458
+ * that relay kept the key's older packet for good, and an app that restarted and read it first found a contact's offer
459
+ * long answered, answered it again, and waited on it (bug hunt r7a).
403
460
  */
404
461
  private catchUpLater;
405
462
  private scheduleCatchUp;
406
463
  private runCatchUp;
464
+ /** `sent`: told, once the budget took the request, whether the relay takes the packet (a 2xx). */
407
465
  private put;
408
466
  /**
409
467
  * Discovery reads and writes share a bounded per-relay request budget; background requests only part of it, and
@@ -421,12 +479,14 @@ export declare class RelayTransport implements PkarrTransport {
421
479
  * contact that just went away (`DEPARTED_READS`).
422
480
  */
423
481
  private heldFor;
424
- /** A group's read of `key` asks: it waits for its turn from now on, unless it is taken (`readsAhead`). */
482
+ /** What is left of the community members' way back allowance on this relay (`WAY_BACK_SHARE`); its reads leave a write the last of it. */
483
+ private wayBackLeft;
484
+ /** A group's read of `key`, or a chat's watch read, asks: it waits for its turn from now on, unless it is taken (`readsAhead`). */
425
485
  private readAsked;
426
486
  /**
427
487
  * Keys a group reads, still asking (within `WATCH_TURN_MS`), that were read longer ago than `key`: a share keeps a
428
488
  * request for each. With `watchLane`, only watched keys the same other limits hold: one the groups' burst holds back
429
- * would keep a turn it cannot take.
489
+ * would keep a turn it cannot take. The chats' watched keys only in their own lane (`CHAT_WATCH_SHARE`).
430
490
  */
431
491
  private readsAhead;
432
492
  /** A read of `key` that takes turns asks: it waits for its turn from now on, unless it is taken (`turnAhead`). */
@@ -449,6 +509,11 @@ export declare class RelayTransport implements PkarrTransport {
449
509
  private chatNeed;
450
510
  /** How long groups still leave a chat its reserve on this relay (`CHAT_RESERVE`); a chat's need a minute old goes. */
451
511
  private chatReservedFor;
512
+ /**
513
+ * How long a chat's packet another relay already took waits for this one: while chats need the relays, a copy takes
514
+ * none of the requests their reserve keeps (`chatReserveOf`), as a group's request does not. 0 when it goes now.
515
+ */
516
+ private spareHeldFor;
452
517
  /** Requests allowed to this relay a minute: this client's budget, or the relay's own share (`RELAY_REQUESTS_PER_MINUTE`). */
453
518
  private limitOf;
454
519
  /** What the chats that need the relays keep on this relay (`CHAT_RESERVE_PER_CHAT`), never less than `reserveOf`. */
@@ -55,11 +55,32 @@ export interface PkarrRequestOptions {
55
55
  * restarts publishes its offer then. A few may go over the relay's minute (`DEPARTED_READS` in relay.ts).
56
56
  */
57
57
  departed?: boolean;
58
+ /**
59
+ * A read of a contact that was live when this app last ran, made before any read of it this run was answered
60
+ * (`LinkSessionOptions.resumed`): the link's offer waits on it. A group edge's goes on the edges' floor
61
+ * (`GROUP_SIGNALING_ALLOWANCE_SHARE` in relay.ts).
62
+ */
63
+ resume?: boolean;
64
+ /**
65
+ * A community member's way back to its group while it has no edge up there (`Communities.wayBack`): its readings of the
66
+ * beacon and its request in a hub's lobby. Its own small allowance past the relay's minute (`WAY_BACK_SHARE` in
67
+ * relay.ts), not the edges' signaling's.
68
+ */
69
+ back?: boolean;
58
70
  /**
59
71
  * `publishPayload` only: the payload was signed in this process, dated so (a group edge's, `CarriedTransport`). Its
60
72
  * signature is not checked again on the way to the relays, as `RelayTransport.putSigned`'s is not.
61
73
  */
62
74
  signedAt?: bigint;
75
+ /**
76
+ * `publishPayload` only, with `signedAt`: the same records signed again, dated past `after` (what a relay that answered
77
+ * 409 holds under the key); null when a newer packet of the key took over. The relays' transport puts that one at
78
+ * once rather than leave the relay's copy in place until the next publish (`RelayTransport.publishPayload`).
79
+ */
80
+ redate?: (after: bigint) => {
81
+ payload: Uint8Array;
82
+ signedAt: bigint;
83
+ } | null;
63
84
  }
64
85
  /**
65
86
  * `transport` with `extra` added to every request's options: a group's edges say `group` so. The optional methods