@ghostlytools/sdk 1.4.4 → 1.5.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 (32) hide show
  1. package/dist/app.js +15 -7
  2. package/dist/app.js.map +1 -1
  3. package/dist/core.js +2 -2
  4. package/dist/{fakes-Cg-kTSO_.js → fakes-CdgaBLS1.js} +2 -2
  5. package/dist/{fakes-Cg-kTSO_.js.map → fakes-CdgaBLS1.js.map} +1 -1
  6. package/dist/fakes.js +1 -1
  7. package/dist/index.js +2 -2
  8. package/dist/{keet-identity-key-BHXtiqy8.js → keet-identity-key-D_bUxyiq.js} +2 -2
  9. package/dist/{keet-identity-key-BHXtiqy8.js.map → keet-identity-key-D_bUxyiq.js.map} +1 -1
  10. package/dist/{src-BdAF18HA.js → src-D9oJLTXM.js} +863 -83
  11. package/dist/src-D9oJLTXM.js.map +1 -0
  12. package/dist/testing.js +3 -3
  13. package/dist/types/core/src/callSignal.d.ts +33 -4
  14. package/dist/types/core/src/catchUp.d.ts +18 -5
  15. package/dist/types/core/src/dhtDelivery.d.ts +4 -4
  16. package/dist/types/core/src/ghostlink.d.ts +54 -1
  17. package/dist/types/core/src/groupCommunity.d.ts +27 -3
  18. package/dist/types/core/src/groupEdits.d.ts +6 -0
  19. package/dist/types/core/src/groupSession.d.ts +6 -3
  20. package/dist/types/core/src/index.d.ts +1 -0
  21. package/dist/types/core/src/miniApp.d.ts +39 -9
  22. package/dist/types/core/src/pairedAppRanges.d.ts +188 -0
  23. package/dist/types/core/src/pairedCapabilities.d.ts +6 -1
  24. package/dist/types/core/src/pairedEdits.d.ts +14 -1
  25. package/dist/types/core/src/relay.d.ts +12 -1
  26. package/dist/types/core/src/relayBreaker.d.ts +7 -2
  27. package/dist/types/core/src/signal.d.ts +4 -1
  28. package/dist/types/core/src/statusCards.d.ts +21 -1
  29. package/dist/{verify-BUV-kmKL.js → verify-DMeDznOh.js} +2 -2
  30. package/dist/{verify-BUV-kmKL.js.map → verify-DMeDznOh.js.map} +1 -1
  31. package/package.json +1 -1
  32. package/dist/src-BdAF18HA.js.map +0 -1
package/dist/testing.js CHANGED
@@ -1,7 +1,7 @@
1
- import { Du as IdentityExchange, Ea as decodeBolt11, Fu as newIdentityBinding, Mu as identityStatement, YS as createIdentity, _u as IDENTITY_MAX_EVIDENCE, ku as emptyIdentityLedger, ta as isBitcoinAddress } from "./src-BdAF18HA.js";
1
+ import { CC as createIdentity, Iu as IDENTITY_MAX_EVIDENCE, Ju as emptyIdentityLedger, Ku as IdentityExchange, Oa as decodeBolt11, Zu as identityStatement, ed as newIdentityBinding, ra as isBitcoinAddress } from "./src-D9oJLTXM.js";
2
2
  import { l as providerDescriptorProblems, o as isNothingSpentError } from "./types-DvtCy3WB.js";
3
- import { i as verifyIdentity, r as descriptorProblems } from "./verify-BUV-kmKL.js";
4
- import { _ as fakeAddress, a as fakeAccount, b as fakeOnchain, c as fakeKeySign, d as fakeRecord, f as fakeRecordText, g as TEST_PROVIDERS_FLAG, h as FakeOnchainProvider, i as TEST_IDENTITIES_FLAG, l as fakeKeySubject, m as FakeLightningProvider, n as FAKE_ISSUER, o as fakeAccountToken, p as testIdentitiesEnabled, r as FAKE_RECORD_HOST, s as fakeKey, t as FAKE_IDENTITY_PROVIDERS, u as fakeKeyring, v as fakeInvoice, x as testProvidersEnabled, y as fakeLightning } from "./fakes-Cg-kTSO_.js";
3
+ import { i as verifyIdentity, r as descriptorProblems } from "./verify-DMeDznOh.js";
4
+ import { _ as fakeAddress, a as fakeAccount, b as fakeOnchain, c as fakeKeySign, d as fakeRecord, f as fakeRecordText, g as TEST_PROVIDERS_FLAG, h as FakeOnchainProvider, i as TEST_IDENTITIES_FLAG, l as fakeKeySubject, m as FakeLightningProvider, n as FAKE_ISSUER, o as fakeAccountToken, p as testIdentitiesEnabled, r as FAKE_RECORD_HOST, s as fakeKey, t as FAKE_IDENTITY_PROVIDERS, u as fakeKeyring, v as fakeInvoice, x as testProvidersEnabled, y as fakeLightning } from "./fakes-CdgaBLS1.js";
5
5
  import { afterEach, describe, expect, it, vi } from "vitest";
6
6
  //#region ../browser/src/engine/paymentAdapters/providers/contractSuite.ts
7
7
  var WAIT = 1e4;
@@ -81,6 +81,12 @@ export interface CallMedia {
81
81
  restartsIce?: boolean;
82
82
  /** Why the screen cannot be shared, where it cannot: the call window shows it on the share button, turned off. */
83
83
  screenUnavailable?: string;
84
+ /**
85
+ * Its connections keep to the configuration's relay policy (`iceTransportPolicy: "relay"`): they gather and use
86
+ * only the TURN server's candidates, so a contact never learns this device's address. The browser's own media
87
+ * does; a stand-in that does not say so is not used for a call while "Hide my IP from contacts" is on.
88
+ */
89
+ keepsToRelays?: boolean;
84
90
  /**
85
91
  * `getUserMedia` captures from the `deviceId` asked for, and `replaceTrack` on the audio sender switches the
86
92
  * microphone: the profile's devices and the call's device menu work as with the browser's own media.
@@ -100,8 +106,25 @@ export interface CallIceServer {
100
106
  * A call's WebRTC configuration: the apps' STUN servers, then the profile's own (Settings → Network → ICE
101
107
  * servers: a TURN relay, typically). A relay is what connects a call when no direct path works: a VPN that takes
102
108
  * every packet through its tunnel, or a NAT that maps each destination apart.
109
+ *
110
+ * `relayOnly` ("Hide my IP from contacts", WISP 100 § Relay only): the profile's TURN servers alone, no STUN server
111
+ * (the apps' or the profile's), and the relay policy, so the connection gathers and uses relay candidates only. With
112
+ * no usable TURN server it has no server at all, and finds no candidate: it fails, it never goes direct.
103
113
  */
104
- export declare function callRtcConfig(extra?: readonly CallIceServer[]): RTCConfiguration;
114
+ export declare function callRtcConfig(extra?: readonly CallIceServer[], { relayOnly }?: {
115
+ relayOnly?: boolean;
116
+ }): RTCConfiguration;
117
+ /**
118
+ * The WebRTC configuration of a chat's data link or a group's edge, from the profile's settings: its ICE servers,
119
+ * and "Hide my IP from contacts" (`relayOnly`), as a call's (`callRtcConfig`). No candidate pool: an app holds one
120
+ * such connection per chat and per group member, and a call only one.
121
+ */
122
+ export declare function contactRtcConfig(settings: {
123
+ iceServers?: readonly CallIceServer[];
124
+ relayOnly?: boolean;
125
+ }): RTCConfiguration;
126
+ /** Whether a connection keeps to relays (`iceTransportPolicy: "relay"`): what it sends a contact is then relay candidates only. */
127
+ export declare function keepsToRelays(pc: Pick<RTCPeerConnection, "getConfiguration"> | null | undefined): boolean;
105
128
  /**
106
129
  * How many candidates a signal on the chat session carries (`paired-call`, WISP 601): the receiver takes eight.
107
130
  * A compatibility chat's `_call` record keeps to one host and one server reflexive candidate (a DHT packet's worth).
@@ -122,18 +145,24 @@ export declare const PAIRED_CALL_CANDIDATES = 8;
122
145
  *
123
146
  * UDP only, loopback, link-local and unspecified addresses left out (loopback kept with `loopback`), the related
124
147
  * address dropped (it is informational, and an IPv6 one broke apps before 0.5).
148
+ *
149
+ * `relayOnly` ("Hide my IP from contacts"): relay candidates alone, whatever else the connection gathered. A relay
150
+ * candidate's address is the TURN server's; its related address, dropped as every one is, would be this device's.
125
151
  */
126
- export declare function pickCallCandidates(candidates: readonly string[], max?: number, { loopback }?: {
152
+ export declare function pickCallCandidates(candidates: readonly string[], max?: number, { loopback, relayOnly }?: {
127
153
  loopback?: boolean | undefined;
154
+ relayOnly?: boolean | undefined;
128
155
  }): string[];
129
156
  /**
130
157
  * The parameters of a call signal, from an SDP. `maxCandidates` above two (a signal on the chat session) carries
131
158
  * the candidates `pickCallCandidates` chooses; the default keeps a compatibility chat's one host and one server
132
- * reflexive candidate.
159
+ * reflexive candidate. `relayOnly` ("Hide my IP from contacts"): relay candidates only, in either; a compatibility
160
+ * chat's two then go to the first two relay ones.
133
161
  */
134
- export declare function extractParamsFromSdp(sdp: string, { maxCandidates, loopback }?: {
162
+ export declare function extractParamsFromSdp(sdp: string, { maxCandidates, loopback, relayOnly }?: {
135
163
  maxCandidates?: number;
136
164
  loopback?: boolean;
165
+ relayOnly?: boolean;
137
166
  }): Partial<CallSignal>;
138
167
  /** Offers, answers and hang-ups older (or further in the future) than this are ignored. */
139
168
  export declare const CALL_SIGNAL_MAX_AGE_MS = 120000;
@@ -21,6 +21,11 @@ export interface CatchUpHooks<F> {
21
21
  handled?(to: string): Promise<CatchUpHandled>;
22
22
  /** Whether the group still answers: an answer stops when it no longer does. */
23
23
  active(): boolean;
24
+ /**
25
+ * What names a frame that a newer answer leaves out while it is on its way (`handled` not resolved yet), or undefined
26
+ * for one that always goes. Absent: a newer answer has every frame of its own.
27
+ */
28
+ key?(frame: F): string | undefined;
24
29
  }
25
30
  /**
26
31
  * Catch-up answers, a slice at a time (`CATCH_UP_SLICE`), with two slices at most not handled yet by the member's app
@@ -33,15 +38,23 @@ export declare class CatchUpAnswers<F> {
33
38
  private readonly hooks;
34
39
  /** Answers still going out, per member: what is left of each. */
35
40
  private going;
41
+ /**
42
+ * Per member, the frames sent (`hooks.key`) whose `handled` has not resolved yet: still waiting in its app, which asks
43
+ * again every 10 s while it handles 1 or 2 a second, and each answer sent the same ones again (200 missed went 1,009
44
+ * times). Left out of a newer answer until handled; one handled and still missing (lost) goes in the next.
45
+ */
46
+ private onTheirWay;
36
47
  constructor(hooks: CatchUpHooks<F>);
37
48
  /**
38
49
  * The first two slices go now, the rest without holding the group's other frames back. A newer answer to the same
39
- * member goes after what is left of the last, without the frames still queued there (the same objects: a store's);
40
- * it took their place before, and left out what the member's `have` said it held: a live frame of an author raises
41
- * it above that author's frames still queued, which were lost for good. A frame the edge did not take ends the answer
42
- * (the member asks again when its edge opens).
50
+ * member goes after what is left of the last, without the frames still queued there (the same objects: a store's)
51
+ * nor those still on their way (`onTheirWay`); it took their place before, and left out what the member's `have`
52
+ * said it held: a live frame of an author raises it above that author's frames still queued, which were lost for
53
+ * good. A frame the edge did not take ends the answer (the member asks again when its edge opens).
43
54
  */
44
55
  handOut(to: string, frames: F[]): void;
45
- /** The next slice of `rest` to `to`: false, and nothing left, when the edge did not take one. */
56
+ /** The next slice of `rest` to `to`, as sent: undefined, and nothing left, when the edge did not take one. */
46
57
  private sendSlice;
58
+ /** A slice's frames (`keys`) are on their way to `to` until `done`: its app handled them, or cannot say (`false`). */
59
+ private track;
47
60
  }
@@ -418,10 +418,10 @@ export declare class DhtDelivery {
418
418
  */
419
419
  private unusedInviteAge;
420
420
  /**
421
- * The wait between reads of the mailbox of a joined chat whose invite someone else used first (`inviteTaken`), before
422
- * it pinned anyone: nothing is awaited from its inviter, so it is read as an unused invite of its age (counted from
423
- * the join) from the notice on, however few other invites the app holds. One slow read stays, so a chat whose invite
424
- * turns out not to be taken (`untaken`) still notices. Undefined for any other chat.
421
+ * The wait between reads of the mailbox of a joined chat whose invite someone else used first (`inviteTaken`), whether
422
+ * or not its look-up pinned the inviter first (`unanswered`): nothing is awaited from its inviter, so it is read as an
423
+ * unused invite of its age (counted from the join) from the notice on, however few other invites the app holds. One
424
+ * slow read stays, so a chat whose invite turns out not to be taken (`untaken`) still notices. Undefined for any other chat.
425
425
  */
426
426
  private takenInviteWait;
427
427
  private schedule;
@@ -19,6 +19,7 @@ import type { ResolvedLink } from "./records.js";
19
19
  import { type ServiceAd } from "./services.js";
20
20
  import { type SessionCapability } from "./pairedCapabilities.js";
21
21
  import { type AppFrameEvent, type AppSendError } from "./pairedApps.js";
22
+ import { type AppRangeTask } from "./pairedAppRanges.js";
22
23
  import { type WakeTarget } from "./pairedWake.js";
23
24
  import { type WireReaction } from "./reactions.js";
24
25
  import { type WirePin } from "./pins.js";
@@ -361,6 +362,13 @@ export interface GhostLinkEvents {
361
362
  onAppFrame?(event: AppFrameEvent): void;
362
363
  /** Both sides offer `apps/1` on the open session (true), or no longer (false). */
363
364
  onAppsSupport?(supported: boolean): void;
365
+ /**
366
+ * The contact's app asks for a range of a file this side's app serves (`app-ranges/1`): read it and give the bytes to
367
+ * `sendAppRange`, or say why not with `failAppRange`. Already checked against the serve ids and the requests in
368
+ * flight; `task.live` turns false when it no longer matters. Settle every task, live or not, with one of the two: a
369
+ * task the contact cancelled holds its place among the app's requests in flight until then.
370
+ */
371
+ onAppRangeTask?(task: AppRangeTask): void;
364
372
  onStatus?(status: LinkStatus): void;
365
373
  onDataLinkState?(state: DataLinkState): void;
366
374
  /** What a WebRTC attempt of this link said about direct connections from this device (`directPath.ts`). */
@@ -480,6 +488,11 @@ export interface GhostLinkOptions {
480
488
  * side (WISP 1200 § In a chat). Behind the apps feature flag.
481
489
  */
482
490
  appsSupport?: boolean;
491
+ /**
492
+ * With `appsSupport`, offer `app-ranges/1`: the contact's app reads, in ranges, a file this side's app serves, and
493
+ * the other way (WISP 1200 § A read lane to the contact). The owner's `onAppRangeTask` then reads the bytes.
494
+ */
495
+ appRangesSupport?: boolean;
483
496
  /**
484
497
  * The apps this side has open in this chat (chat app id to version), kept by the caller across this link's restarts.
485
498
  * Each new session says `open` for each. Without it the link keeps its own.
@@ -693,6 +706,8 @@ export declare class GhostLink {
693
706
  private readonly typingReceiver;
694
707
  /** Mini-apps on this session (`apps/1`): this side's open apps (kept across sessions), the peer's, the limits. */
695
708
  private readonly apps;
709
+ /** The read lane on this session (`app-ranges/1`): what this side serves and what it asked; none of it outlives the session. */
710
+ private readonly appRanges;
696
711
  /** Reaction frames the contact may send per window; the rest go unconfirmed and come again. */
697
712
  private readonly reactionsReceived;
698
713
  /** Pin frames the contact may send per window; the rest go unconfirmed and come again. */
@@ -900,7 +915,10 @@ export declare class GhostLink {
900
915
  private publishRecovered;
901
916
  private emitPairingState;
902
917
  get presence(): PeerPresence;
903
- /** Someone else used the invite first, and this side never pinned its inviter: there is nobody to pair with. */
918
+ /**
919
+ * Someone else used the invite first: there is nobody to pair with, whether or not this side's look-up pinned its
920
+ * inviter from the envelope put out before anyone joined (said only while unproven: never live, nothing confirmed).
921
+ */
904
922
  get takenFromUs(): boolean;
905
923
  /**
906
924
  * The session runs on the joiner's link key, which every copy of the invite derives: while the invite is taken from
@@ -1459,6 +1477,41 @@ export declare class GhostLink {
1459
1477
  * channel each time it drains to files' line and keep the file from moving.
1460
1478
  */
1461
1479
  sendAppData(app: string, data: unknown): AppSendError | null;
1480
+ /** Both sides offer `app-ranges/1` (and `apps/1`) on the open session: an app's files can be read from the other side. */
1481
+ get supportsAppRanges(): boolean;
1482
+ /** Why the read lane cannot be used for `app` now, or null when it can: open on both sides, on a live session that has it. */
1483
+ private appRangesRefusal;
1484
+ /**
1485
+ * Lets the contact's `app` read `file` (what this side's app calls it) for as long as both have the app open on this
1486
+ * session: the serve id to tell it, or why not.
1487
+ */
1488
+ serveAppFile(app: string, file: string): {
1489
+ serve: string;
1490
+ } | {
1491
+ error: "not-open" | "offline" | "peer-closed";
1492
+ };
1493
+ /** Ends a serve; false when it was not served (any more). */
1494
+ unserveAppFile(serve: string): boolean;
1495
+ /** The serve ids `app` has given out on this session. */
1496
+ appServes(app: string): string[];
1497
+ /**
1498
+ * Reads `length` bytes at `offset` of what the contact's `app` serves as `serve`: the bytes (fewer at the end of the
1499
+ * file) and the file's size. Rejects with an `Error` whose message is an `AppRangeReadError` or `not-open`.
1500
+ */
1501
+ readAppRange(app: string, serve: string, offset: number, length: number): Promise<{
1502
+ bytes: Uint8Array;
1503
+ size: number;
1504
+ }>;
1505
+ /**
1506
+ * The bytes `task` asked for (fewer at the end of the file, none past it) and the file's size: sent in chunks as the
1507
+ * channel has room, sharing files' line (`filesWritable`), as binary messages where `files/4` is agreed, then
1508
+ * `ar-end`. Stops when the task is no longer live or the session changes.
1509
+ */
1510
+ sendAppRange(task: AppRangeTask, bytes: Uint8Array, size: number): Promise<void>;
1511
+ /** `task`'s file cannot be read: `changed` or `gone` goes in place of its bytes (nothing once it is no longer live, but its place frees). */
1512
+ failAppRange(task: AppRangeTask, error: "changed" | "gone"): void;
1513
+ /** An `ar-*` frame from the contact, on a session that agreed `app-ranges/1`. */
1514
+ private receiveAppRange;
1462
1515
  /** What the contact had open is gone (`apps/1` is no longer agreed, or this link stopped): each app hears it now. */
1463
1516
  private appsEnded;
1464
1517
  private appsGrace;
@@ -112,6 +112,11 @@ export interface CommunityCommit {
112
112
  n?: string;
113
113
  /** The leaver's signature, in a `leave`. */
114
114
  ls?: string;
115
+ /**
116
+ * The leaver's signature over the admission the leave ends (`leaveStatement3`), in a `leave`. Outside the hash and
117
+ * the committer's signature, which an app from before computes without it: it stands by the leaver's key alone.
118
+ */
119
+ ls3?: string;
115
120
  ts: number;
116
121
  c: string;
117
122
  sig: string;
@@ -125,6 +130,14 @@ export declare function communityGroupId(creator: string, nonce: string): string
125
130
  export declare const leaveStatement: (g: string, s: string) => Uint8Array<ArrayBufferLike>;
126
131
  /** What the member who committed a leave (`h`) had heard of the leaver then: `e:h16` → its highest number there. */
127
132
  export declare const leftStatement: (g: string, h: string, hi: Record<string, number>) => Uint8Array<ArrayBufferLike>;
133
+ /** A leave of one admission: `h` is the hash of the commit that last put `s` in the roster (its `add`, or the `create` it signed). */
134
+ export declare const leaveStatement3: (g: string, s: string, h: string) => Uint8Array<ArrayBufferLike>;
135
+ /**
136
+ * Whether a leave holds after `before` (the commits before it, newest first): its `ls3` names the commit that last
137
+ * admitted the leaver, or, from an app that signs no such statement, no earlier leave carries its `ls`. `ls` says the
138
+ * same for every admission of a member, so by itself it ends one admission only.
139
+ */
140
+ export declare function leaveStands(leave: Pick<CommunityCommit, "g" | "s" | "ls" | "ls3">, before: Iterable<CommunityCommit>): boolean;
128
141
  /** The secret of an epoch that adds, re-roles or re-links: from the previous one and the commit. */
129
142
  export declare function derivedSecret(previous: Uint8Array, untaggedHash: string): Uint8Array;
130
143
  /**
@@ -135,15 +148,21 @@ export declare function communityRoster(previous: Roster | null, c: Pick<Communi
135
148
  /**
136
149
  * One commit against its parent (null for a genesis) and the parent's roster: shape, id, link,
137
150
  * authority, roster arithmetic, roster hash and signature. The confirmation tag is checked once
138
- * the secret is known.
151
+ * the secret is known. `before`: the commits before it on its branch, newest first; given, a `leave` is held to the
152
+ * admission it ends (`leaveStands`). A member gives it for every commit it takes in after its own admission; the chain
153
+ * of a welcome is not held to it (`verifyCommunityChain`).
139
154
  */
140
- export declare function verifyCommunityCommit(raw: unknown, parent: CommunityCommit | null, parentRoster: Roster | null, groupId?: string): {
155
+ export declare function verifyCommunityCommit(raw: unknown, parent: CommunityCommit | null, parentRoster: Roster | null, groupId?: string, before?: Iterable<CommunityCommit>): {
141
156
  commit: CommunityCommit;
142
157
  roster: Roster;
143
158
  } | {
144
159
  error: string;
145
160
  };
146
- /** A whole chain from its genesis; the rosters after each commit and the entry key at the end. */
161
+ /**
162
+ * A whole chain from its genesis; the rosters after each commit and the entry key at the end. What a newcomer is
163
+ * handed: a `leave` in it is not held to the admission it ends, since a chain from before 2026-10-10 may hold a
164
+ * member's second leave under the one statement there was, and no newcomer could enter that group again.
165
+ */
147
166
  export declare function verifyCommunityChain(raw: unknown, groupId?: string): {
148
167
  chain: CommunityCommit[];
149
168
  roster: Roster;
@@ -207,6 +226,7 @@ export interface CommunityLeaveFrame {
207
226
  g: string;
208
227
  s: string;
209
228
  ls: string;
229
+ ls3?: string;
210
230
  }
211
231
  /**
212
232
  * The mark of a leave (`h`, the commit's full hash), signed by the member who committed it: how far it had heard the
@@ -311,6 +331,7 @@ export interface CommunityState {
311
331
  pendingLeaves: {
312
332
  s: string;
313
333
  ls: string;
334
+ ls3?: string;
314
335
  }[];
315
336
  /** Leave commit (full hash) → its mark, as its committer signed it (`group-left`), oldest first. Absent in older states. */
316
337
  left?: Record<string, {
@@ -541,6 +562,8 @@ export declare class CommunitySession {
541
562
  */
542
563
  private rebuild;
543
564
  private placeSide;
565
+ /** The commit `h` and those before it on its branch, newest first. */
566
+ private ancestry;
544
567
  private rosterOf;
545
568
  /** The roster after a commit: cached for the window and the side, replayed for an older commit of the main branch. */
546
569
  private rosterAt;
@@ -672,6 +695,7 @@ export declare class CommunitySession {
672
695
  text: string;
673
696
  mentions?: readonly GroupMention[];
674
697
  card?: StatusCard;
698
+ remove?: boolean;
675
699
  }, nick?: string, now?: number): Promise<{
676
700
  id: string;
677
701
  } | {
@@ -16,6 +16,10 @@ import { type StatusCard } from "./statusCards.js";
16
16
  * `sc` is the status card of this version (WISP 405 · Status Cards); an edit with one may be numbered up to
17
17
  * `STATUS_CARD_LIMITS.edits`, one without only up to `MAX_EDITS_PER_MESSAGE`.
18
18
  *
19
+ * A removal (WISP 400 § Delete for everyone) is an edit with `rm: true` and a fallback text, nothing else beside it,
20
+ * numbered up to `MAX_REMOVAL_NUMBER`: in a mesh group's box as `{ "text", "rm": true }`, in a community's frame beside
21
+ * `text`. A `rm` other than `true` is no edit.
22
+ *
19
23
  * Older apps drop both: a mesh session ignores a `t` it does not know, a community app the `x` frames it does not know.
20
24
  */
21
25
  export declare const GROUP_EDIT_FRAME = "group-edit";
@@ -32,6 +36,8 @@ export interface GroupEdit {
32
36
  k?: GroupMention[];
33
37
  /** The status card of this version (WISP 405 · Status Cards). */
34
38
  sc?: StatusCard;
39
+ /** The author deleted the message for everyone: `m` is only a fallback. */
40
+ rm?: true;
35
41
  }
36
42
  /** An edit as a group hands it to the engine: `sender` is the member it is authenticated as. */
37
43
  export interface GroupIncomingEdit extends GroupEdit {
@@ -496,10 +496,12 @@ export declare class GroupSession {
496
496
  /** Members other than me, in the current roster. */
497
497
  get others(): string[];
498
498
  /**
499
- * Whether `key` could read message `messageId` (`<s>:<e>:<n>`) and still can: in the roster of its epoch, and in the
500
- * roster now. A holder serves a group file only to such a member (WISP 503 § Asking).
499
+ * Whether `key` could read message `messageId` (`<s>:<e>:<n>`) and still can: in the roster now, and in the roster of
500
+ * its epoch or, given the message's time `ts`, in the roster of the epoch its author, behind on the chain, said it
501
+ * again under (`saidAgainEpoch`): the newest after its own that comes before any `add` dated later than it. That
502
+ * member read it under its first id. A holder serves a group file only to such a member (WISP 503 § Asking).
501
503
  */
502
- couldRead(key: string, messageId: string): boolean;
504
+ couldRead(key: string, messageId: string, ts?: number): boolean;
503
505
  role(key: string): GroupRole | undefined;
504
506
  /** The group's picture, if it has one. */
505
507
  get picture(): string | undefined;
@@ -666,6 +668,7 @@ export declare class GroupSession {
666
668
  text: string;
667
669
  mentions?: readonly GroupMention[];
668
670
  card?: StatusCard;
671
+ remove?: boolean;
669
672
  }, to?: string): Promise<{
670
673
  sent: number;
671
674
  } | {
@@ -47,6 +47,7 @@ export * from "./pairedCapabilities.js";
47
47
  export * from "./pairedCalls.js";
48
48
  export * from "./pairedTyping.js";
49
49
  export * from "./pairedApps.js";
50
+ export * from "./pairedAppRanges.js";
50
51
  export * from "./webPush.js";
51
52
  export * from "./pairedWake.js";
52
53
  export * from "./pairedEdits.js";
@@ -91,12 +91,35 @@ export interface MiniAppApi {
91
91
  }): Promise<ArrayBuffer>;
92
92
  /** Drops one link, or every link with "all". The file itself is never touched. */
93
93
  forget(id: string): Promise<void>;
94
+ /**
95
+ * Lets the same app on the contact's side read one kept file (the `chat` permission too, in a chat open on both
96
+ * sides): answers a serve id for the app to tell its contact in its own `chat.send`. It lasts until `unserve`, this
97
+ * side or the contact closes the app, or the session ends.
98
+ */
99
+ serve(id: string): Promise<string>;
100
+ /** Ends one serve. A serve id that is no longer served is no error. */
101
+ unserve(serveId: string): Promise<void>;
102
+ };
103
+ /**
104
+ * Files the contact's app serves in this chat (the `chat` permission): absent in a client that has no read lane, so
105
+ * an app tests for it and keeps its own way for such a contact.
106
+ */
107
+ remote?: {
108
+ /** At most `MINI_APP_LIMITS.remoteReadBytes` from `offset`; fewer at the end of the file. */
109
+ read(serveId: string, range: {
110
+ offset: number;
111
+ length: number;
112
+ }): Promise<ArrayBuffer>;
113
+ /** The served file's size in bytes. */
114
+ stat(serveId: string): Promise<{
115
+ size: number;
116
+ }>;
94
117
  };
95
118
  /** Ends the app. */
96
119
  close(): Promise<void>;
97
120
  }
98
121
  /** The message types on the port (web, extension) or through `app_broker` (Desktop). */
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";
122
+ export type MiniAppRequestType = "context" | "file" | "storage.get" | "storage.set" | "storage.delete" | "storage.keys" | "chat.send" | "files.pick" | "files.list" | "files.read" | "files.forget" | "files.serve" | "files.unserve" | "remote.read" | "remote.stat" | "close";
100
123
  /** A request from the app: `{id, type, args}`. The broker refuses an unknown `type`. */
101
124
  export interface MiniAppRequest {
102
125
  id: number;
@@ -113,18 +136,23 @@ export interface MiniAppRequest {
113
136
  * - `bad-path`: a `file` path that is not a string of 1 to 1024 characters.
114
137
  * - `bad-request`: a request that is not `{id, type, args}` with JSON arguments, or whose arguments are not the call's.
115
138
  * - `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.
139
+ * - `changed`: `files.read` (or the contact's `remote.read` of it) of a file whose size or date changed since it was
140
+ * picked: it is picked again to be read.
117
141
  * - `failed`: anything else; the client's own words never reach the app.
118
142
  * - `full`: a storage write would take the scope past 5 MiB (each key counts 128 bytes, its own bytes eight times and
119
143
  * 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.
144
+ * - `gone`: `files.read` (or the contact's `remote.read` of it) of a file that is no longer there, or that the client
145
+ * cannot read now (`available` false), or of an id it does not keep; `files.serve` of such an id.
122
146
  * - `no-file`: the bundle has no such file.
123
147
  * - `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.
148
+ * `files` permission, or in a client that cannot keep links; `files.serve` also without `chat` or with the app opened
149
+ * alone, and `remote.*` without `chat` or with the app opened alone.
125
150
  * - `not-open`: `chat.send` before this side's chat has the app open.
126
- * - `offline`: `chat.send` while the chat's session is not live. Nothing is kept to send later.
127
- * - `peer-closed`: `chat.send` while the contact has not opened the app (or its client does not offer `apps/1`).
151
+ * - `not-served`: `remote.read` or `remote.stat` of a serve id the contact does not serve now (never, or no longer).
152
+ * - `offline`: `chat.send`, `files.serve`, `remote.read` or `remote.stat` while the chat's session is not live.
153
+ * Nothing is kept to send later.
154
+ * - `peer-closed`: `chat.send` or `files.serve` while the contact has not opened the app (or its client does not offer
155
+ * `apps/1`, or for `files.serve` and `remote.*` the read lane, `app-ranges/1`).
128
156
  * - `stopped`: a store removed or the publisher revoked the version running.
129
157
  * - `too-fast`: past 50 requests a second, past 48 `chat.send` frames a second, or a `chat.send` while the chat's
130
158
  * connection is still sending earlier ones (back off and send again).
@@ -133,7 +161,7 @@ export interface MiniAppRequest {
133
161
  *
134
162
  * A later client may add a code: treat one you do not know as `failed`.
135
163
  */
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"];
164
+ 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", "not-served", "offline", "peer-closed", "stopped", "too-fast", "too-large", "unknown-type"];
137
165
  export type MiniAppErrorCode = typeof MINI_APP_ERROR_CODES[number];
138
166
  /** The code of a refused `ghostly.*` call (the rejection's `Error`), or null for anything that is not one. */
139
167
  export declare function miniAppErrorCode(error: unknown): MiniAppErrorCode | null;
@@ -173,13 +201,15 @@ export declare const MINI_APP_LIMITS: {
173
201
  /** Requests per second, per app. */
174
202
  readonly requestsPerSecond: 50;
175
203
  /**
176
- * Bytes of `file`, `files.read` and `files.list` answers per second, per app, counted together: a whole bundle's
204
+ * Bytes of `file`, `files.read`, `files.list` and `remote.read` answers per second, per app, counted together: a whole bundle's
177
205
  * worth. A request that starts under it is answered whole; past it the request is refused with `too-fast` until the
178
206
  * second has gone.
179
207
  */
180
208
  readonly fileBytesPerSecond: number;
181
209
  /** One `files.read`, at most. */
182
210
  readonly filesReadBytes: number;
211
+ /** One `remote.read`, at most: one `ar-get` of the read lane. */
212
+ readonly remoteReadBytes: number;
183
213
  /** The links an app keeps, at most: a pick that would pass it is refused with `too-large`. */
184
214
  readonly filesEntries: 100000;
185
215
  /** Extensions a `files.pick` may name in `accept`, each 1 to 16 characters of `a-z` and `0-9`. */