@ghostlytools/sdk 1.4.5 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/testing.js CHANGED
@@ -1,7 +1,7 @@
1
- import { Du as IdentityExchange, Ea as decodeBolt11, Fu as newIdentityBinding, Mu as identityStatement, XS as createIdentity, _u as IDENTITY_MAX_EVIDENCE, ku as emptyIdentityLedger, ta as isBitcoinAddress } from "./src-BkkTL_0F.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-DmirvhXS.js";
2
2
  import { l as providerDescriptorProblems, o as isNothingSpentError } from "./types-DvtCy3WB.js";
3
- import { i as verifyIdentity, r as descriptorProblems } from "./verify-BDbn0S5X.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-BESovsfV.js";
3
+ import { i as verifyIdentity, r as descriptorProblems } from "./verify-CwAcEmuz.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-CD1PMHc7.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;
@@ -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. */
@@ -1462,6 +1477,41 @@ export declare class GhostLink {
1462
1477
  * channel each time it drains to files' line and keep the file from moving.
1463
1478
  */
1464
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;
1465
1515
  /** What the contact had open is gone (`apps/1` is no longer agreed, or this link stopped): each app hears it now. */
1466
1516
  private appsEnded;
1467
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";
@@ -239,6 +239,8 @@ export declare class LinkSession {
239
239
  private publishAgain;
240
240
  /** What waits to go out is the presence heartbeat alone (`PRESENCE_HEARTBEAT`): nothing in the packet changed. */
241
241
  private upkeepOnly;
242
+ /** The last write this link asked for was a background one (`retryDelay`). */
243
+ private wroteInBackground;
242
244
  private pollTimer;
243
245
  private heartbeatTimer;
244
246
  private lastActivity;
@@ -390,7 +392,10 @@ export declare class LinkSession {
390
392
  */
391
393
  private publish;
392
394
  private publishOnce;
393
- /** When a publish that failed goes again: when the relays' budget frees a request, if that held it back. */
395
+ /**
396
+ * When a publish that failed goes again: when the relays' budget frees a request, if that held it back; a chat's or a
397
+ * group's write within `PUBLISH_RETRY_MS` meanwhile, which keeps it first in line, a background one when its share frees.
398
+ */
394
399
  private retryDelay;
395
400
  private discoveryResult;
396
401
  private poll;
@@ -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`. */
@@ -0,0 +1,198 @@
1
+ import { isChatAppId } from "./pairedApps.js";
2
+ /**
3
+ * The read lane of mini-apps in a 1:1 chat (WISP 1200 § A read lane to the contact: `app-ranges/1`): the contact's app
4
+ * reads, in ranges, a file this side's app serves, over the chat's session but not through `apps/1`.
5
+ *
6
+ * {"t":"ar-get","a":"<chat app id>","s":"<serve id>","r":7,"o":0,"n":1048576}
7
+ * {"t":"ar-data","a":"<chat app id>","r":7,"o":0,"d":"<base64url>"}
8
+ * {"t":"ar-end","a":"<chat app id>","r":7,"z":734003200}
9
+ * {"t":"ar-err","a":"<chat app id>","r":7,"e":"not-served"}
10
+ * {"t":"ar-cancel","a":"<chat app id>","r":7}
11
+ *
12
+ * The asker sends `ar-get` (request `r`, a number of its own, for `n` bytes at offset `o` of serve `s`) and may send
13
+ * `ar-cancel`; the server answers with the bytes in chunks of at most `APP_RANGE_LIMITS.chunkBytes`, then `ar-end`
14
+ * once every byte asked was sent (fewer at the end of the file), with `z` the served file's size, or `ar-err` instead of
15
+ * any. A read of one byte at 0 is how the asker learns the size. Where `files/4` is on,
16
+ * a chunk is a binary message of kind `APP_RANGE_DATA_KIND` (`encodeAppRangeData`) in place of `ar-data`. It needs
17
+ * `app-ranges/1` in `paired-capabilities` on both sides. A reader ignores keys it does not know, so a later version
18
+ * can add some.
19
+ */
20
+ export declare const APP_RANGE_FRAMES: Set<string>;
21
+ export declare const APP_RANGE_LIMITS: {
22
+ /** One `ar-get`, at most: as one `remote.read` of the app. */
23
+ readonly requestBytes: number;
24
+ /** One chunk, `ar-data` or binary: as a chat file's. */
25
+ readonly chunkBytes: number;
26
+ /** The largest request number: it is 4 bytes in a binary chunk. */
27
+ readonly maxRequest: 4294967295;
28
+ /** Requests a server takes in flight per app; one more is answered `busy`. An asker keeps the rest waiting. */
29
+ readonly inFlight: 4;
30
+ /**
31
+ * The bytes a server takes asks for in one second, its apps together: one more is answered `busy`. Counted as they
32
+ * are asked, so a cancelled one counts as the read it started. Twice the asking app's own budget (16 MiB a second).
33
+ */
34
+ readonly bytesPerSecond: number;
35
+ };
36
+ /**
37
+ * What an `ar-err` says. `not-served`: no serve of that id on this session (never given, or ended); `changed` and
38
+ * `gone`: the file under it, as `files.read` says them; `busy`: past the requests the server takes in flight. A
39
+ * later version may add one: an asker reads a code it does not know as a failure.
40
+ */
41
+ export declare const APP_RANGE_ERRORS: readonly ["not-served", "changed", "gone", "busy"];
42
+ export type AppRangeError = typeof APP_RANGE_ERRORS[number];
43
+ export type AppRangeFrame = {
44
+ t: "ar-get";
45
+ a: string;
46
+ s: string;
47
+ r: number;
48
+ o: number;
49
+ n: number;
50
+ } | {
51
+ t: "ar-data";
52
+ a: string;
53
+ r: number;
54
+ o: number;
55
+ d: string;
56
+ } | {
57
+ t: "ar-end";
58
+ a: string;
59
+ r: number;
60
+ z: number;
61
+ } | {
62
+ t: "ar-err";
63
+ a: string;
64
+ r: number;
65
+ e: string;
66
+ } | {
67
+ t: "ar-cancel";
68
+ a: string;
69
+ r: number;
70
+ };
71
+ /** Why a reader refuses an `ar-*` frame (the vectors' `refusal`). */
72
+ export type AppRangeRefusal = "not-ranges" | "bad-a" | "bad-s" | "bad-r" | "bad-o" | "bad-n" | "bad-d" | "bad-e" | "bad-z";
73
+ /** A serve id as it is on the wire: 22 base64url characters (16 random bytes, no padding), as a chat app id. */
74
+ export declare const isServeId: typeof isChatAppId;
75
+ /** The bytes of `d`, or null when it is not 1 to `chunkBytes` bytes of canonical base64url without padding. */
76
+ export declare function appRangeChunk(d: unknown): Uint8Array | null;
77
+ export declare function appRangeGetFrame(app: string, serve: string, request: number, offset: number, length: number): AppRangeFrame;
78
+ export declare function appRangeDataFrame(app: string, request: number, offset: number, data: Uint8Array): AppRangeFrame;
79
+ export declare function appRangeEndFrame(app: string, request: number, size: number): AppRangeFrame;
80
+ export declare function appRangeErrorFrame(app: string, request: number, error: AppRangeError): AppRangeFrame;
81
+ export declare function appRangeCancelFrame(app: string, request: number): AppRangeFrame;
82
+ /**
83
+ * An `ar-*` frame as the peer sent it, or why a reader must refuse it: an unknown `t`, no valid `a`, an `ar-get`
84
+ * without a valid `s`, a request number that is not 0 to 2^32 - 1, an offset that is not a safe whole number at or
85
+ * above 0, an `n` that is not 1 to `requestBytes` (or runs past 2^53 - 1), a `d` that is not 1 to `chunkBytes` bytes of
86
+ * canonical base64url, an `e` that is not a code (lower case letters and `-`, at most 32), an `ar-end` whose `z` is not
87
+ * a size (a safe whole number at or above 0). Other keys are ignored.
88
+ */
89
+ export declare function readAppRangeFrame(frame: Record<string, unknown>): {
90
+ ok: true;
91
+ frame: AppRangeFrame;
92
+ } | {
93
+ ok: false;
94
+ refusal: AppRangeRefusal;
95
+ };
96
+ /** An `ar-*` frame as the peer sent it, or null when a reader must refuse it (`readAppRangeFrame` says why). */
97
+ export declare function parseAppRangeFrame(frame: Record<string, unknown>): AppRangeFrame | null;
98
+ /**
99
+ * `app-ranges/1` beside `files/4` (WISP 100 § Text and binary messages): a chunk as one binary message of the session,
100
+ * in place of the base64url text of an `ar-data` frame:
101
+ *
102
+ * kind 0x05 (1) | chat app id (16) | request (4, big endian) | offset (8, big endian) | data (1 to `chunkBytes`)
103
+ */
104
+ export declare const APP_RANGE_DATA_KIND = 5;
105
+ /** The binary message for the bytes of request `request` of app `app` at `offset`. Throws on what no receiver would take. */
106
+ export declare function encodeAppRangeData(app: string, request: number, offset: number, data: Uint8Array): Uint8Array;
107
+ /** What a binary message from the contact says, or null when it is not well-formed app range data. `data` is a view of `message`. */
108
+ export declare function decodeAppRangeData(message: Uint8Array): {
109
+ a: string;
110
+ r: number;
111
+ o: number;
112
+ data: Uint8Array;
113
+ } | null;
114
+ /** Why a read of the contact's file failed, as the app hears it (a broker code). */
115
+ export type AppRangeReadError = "not-served" | "changed" | "gone" | "offline" | "peer-closed" | "failed";
116
+ /** A request of the contact's to answer: read `length` bytes of `file` at `offset`, send them, then `finish`. */
117
+ export interface AppRangeTask {
118
+ readonly app: string;
119
+ readonly request: number;
120
+ /** The serve id it came under: the page that served it answers it. */
121
+ readonly serve: string;
122
+ /** What this side's app served, as it named it (a linked file's id). */
123
+ readonly file: string;
124
+ readonly offset: number;
125
+ readonly length: number;
126
+ /**
127
+ * False once the asker cancelled, the app closed or the session ended: send nothing more for it. A task the asker
128
+ * cancelled still holds its place among the app's `inFlight` until it is settled (`finish`, `fail` or `release`).
129
+ */
130
+ readonly live: boolean;
131
+ }
132
+ /**
133
+ * The read lane of one chat, both ways (WISP 1200 § A read lane to the contact). As the side that serves it keeps the
134
+ * serve ids it gave out on this session and answers the contact's `ar-get` for those only, at most
135
+ * `APP_RANGE_LIMITS.inFlight` per app and `bytesPerSecond` asked in all (`busy` past either); the bytes themselves
136
+ * are read and sent by the session, which calls `finish` or `fail` for each task. As the side that asks it sends at
137
+ * most `inFlight` requests per app, keeps
138
+ * the rest waiting, and puts each answer back together, in order, from the offset asked. Serves and requests last one
139
+ * session: `reset` ends them all, `closeApp` those of one app.
140
+ */
141
+ export declare class AppRanges {
142
+ private readonly send;
143
+ private readonly newServeId;
144
+ private readonly now;
145
+ private readonly serves;
146
+ private readonly serving;
147
+ /** Tasks cancelled or unserved that the session is still reading or sending: each counts in its app's `inFlight` until settled. */
148
+ private readonly draining;
149
+ private readonly asking;
150
+ private readonly waiting;
151
+ private nextRequest;
152
+ /** The asks taken in the last second (when, how many bytes) and their sum: what `bytesPerSecond` counts. Kept across sessions. */
153
+ private readonly taken;
154
+ private takenBytes;
155
+ constructor(send: (frame: AppRangeFrame) => void, newServeId?: () => string, now?: () => number);
156
+ /** Lets the contact's `app` read `file` on this session: the serve id to tell it. */
157
+ serve(app: string, file: string): string;
158
+ /** Ends one serve: requests under it still being sent stop. False when it was not served. */
159
+ unserve(serveId: string): boolean;
160
+ /** The serve ids `app` has given out on this session (what the panel's "Sharing with" line shows). */
161
+ servesOf(app: string): string[];
162
+ /** An `ar-get` from the contact: the task to read and send, or null when it was refused (the refusal is sent) or dropped. */
163
+ receiveGet(frame: Extract<AppRangeFrame, {
164
+ t: "ar-get";
165
+ }>): AppRangeTask | null;
166
+ /** An `ar-cancel` from the contact: that request sends nothing more, and its number frees; its place frees once it is settled. */
167
+ receiveCancel(frame: Extract<AppRangeFrame, {
168
+ t: "ar-cancel";
169
+ }>): void;
170
+ /** Every byte of `task` was sent: `ar-end` goes with the file's size, unless the task was dropped meanwhile. */
171
+ finish(task: AppRangeTask, size: number): void;
172
+ /** The file under `task` could not be read: `ar-err` goes in place of the rest, unless the task was dropped meanwhile. */
173
+ fail(task: AppRangeTask, error: "changed" | "gone"): void;
174
+ /** The session stopped working on `task` without an answer (it is no longer live, or the channel went): its place frees, nothing is sent. */
175
+ release(task: AppRangeTask): void;
176
+ /** Reads `length` bytes at `offset` of what the contact's `app` serves as `serve`: the bytes (fewer at the end) and the file's size. */
177
+ read(app: string, serve: string, offset: number, length: number): Promise<{
178
+ bytes: Uint8Array;
179
+ size: number;
180
+ }>;
181
+ /** Bytes of a request of ours, from `ar-data` or a binary chunk. Out of order or past what was asked fails the request. */
182
+ receiveData(app: string, request: number, offset: number, data: Uint8Array): void;
183
+ /** The contact's `ar-end` or `ar-err` for a request of ours. */
184
+ receiveAnswer(frame: Extract<AppRangeFrame, {
185
+ t: "ar-end" | "ar-err";
186
+ }>): void;
187
+ /** `app` closed on either side: its serves end, what it was sending stops and what it asked fails with `error`. */
188
+ closeApp(app: string, error?: AppRangeReadError): void;
189
+ /** The session ended: no serve id lasts into the next, and every request fails with `offline`. */
190
+ reset(): void;
191
+ /** Stops `task` and frees its request number; `draining` keeps it counted until it is settled. */
192
+ private drop;
193
+ /** Frees `task`'s place; false when it was no longer live (nothing to send for it). */
194
+ private take;
195
+ /** Ends `ask` (failing it with `error` when given) and sends the next one waiting for its app. */
196
+ private settle;
197
+ private pump;
198
+ }
@@ -59,11 +59,16 @@ export declare const UPGRADE_CAPABILITY = "upgrade/1";
59
59
  * `pairedApps.ts`). Offered only while the apps feature is on.
60
60
  */
61
61
  export declare const APPS_CAPABILITY = "apps/1";
62
+ /**
63
+ * The read lane of mini-apps (WISP 1200 § A read lane to the contact, `pairedAppRanges.ts`): the contact's app reads a
64
+ * file this side's app serves, in ranges, outside `apps/1`. Offered beside `apps/1` only.
65
+ */
66
+ export declare const APP_RANGES_CAPABILITY = "app-ranges/1";
62
67
  /**
63
68
  * What only a device link offers (WISP 06, `deviceLink.ts`): the frames between a person's own devices. They are in
64
69
  * the type so a device link can announce them, and not in `KNOWN_SESSION_CAPABILITIES`: no chat knows them.
65
70
  */
66
- export type SessionCapability = DeviceCapability | typeof CALLS_CAPABILITY | typeof SERVICES_CAPABILITY | typeof FILES_CAPABILITY | typeof FILES_BINARY_CAPABILITY | typeof TYPING_CAPABILITY | typeof REACTIONS_CAPABILITY | typeof EDIT_CAPABILITY | typeof WAKE_SESSION_CAPABILITY | typeof PIN_CAPABILITY | typeof STATUS_CARD_CAPABILITY | typeof BUTTONS_CAPABILITY | typeof UPGRADE_CAPABILITY | typeof APPS_CAPABILITY;
71
+ export type SessionCapability = DeviceCapability | typeof CALLS_CAPABILITY | typeof SERVICES_CAPABILITY | typeof FILES_CAPABILITY | typeof FILES_BINARY_CAPABILITY | typeof TYPING_CAPABILITY | typeof REACTIONS_CAPABILITY | typeof EDIT_CAPABILITY | typeof WAKE_SESSION_CAPABILITY | typeof PIN_CAPABILITY | typeof STATUS_CARD_CAPABILITY | typeof BUTTONS_CAPABILITY | typeof UPGRADE_CAPABILITY | typeof APPS_CAPABILITY | typeof APP_RANGES_CAPABILITY;
67
72
  /** Every capability this app knows on a session: what `receive` reports changes of. */
68
73
  export declare const KNOWN_SESSION_CAPABILITIES: readonly SessionCapability[];
69
74
  export declare const SESSION_CAPABILITIES_FRAME = "paired-capabilities";