@ghostlytools/sdk 0.0.0-stage → 1.2.4
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/README.md +13 -2
- package/dist/app.js +72 -0
- package/dist/app.js.map +1 -0
- package/dist/core.js +207 -0
- package/dist/core.js.map +1 -0
- package/dist/fakes-JOzOFxn3.js +536 -0
- package/dist/fakes-JOzOFxn3.js.map +1 -0
- package/dist/fakes.js +2 -0
- package/dist/index.js +179 -0
- package/dist/index.js.map +1 -0
- package/dist/keet-identity-key-BLli1rE4.js +76483 -0
- package/dist/keet-identity-key-BLli1rE4.js.map +1 -0
- package/dist/src-BqHTnRWH.js +31296 -0
- package/dist/src-BqHTnRWH.js.map +1 -0
- package/dist/testing.js +330 -0
- package/dist/testing.js.map +1 -0
- package/dist/types/browser/src/engine/paymentAdapters/providers/contractSuite.d.ts +41 -0
- package/dist/types/browser/src/engine/paymentAdapters/providers/lightning.d.ts +103 -0
- package/dist/types/browser/src/engine/paymentAdapters/providers/onchain.d.ts +88 -0
- package/dist/types/browser/src/engine/paymentAdapters/providers/testing.d.ts +89 -0
- package/dist/types/browser/src/engine/paymentAdapters/providers/types.d.ts +151 -0
- package/dist/types/browser/src/plugins/bundled.d.ts +8 -0
- package/dist/types/browser/src/plugins/registry.d.ts +57 -0
- package/dist/types/browser/src/proofs/contract.d.ts +262 -0
- package/dist/types/browser/src/proofs/contractSuite.d.ts +27 -0
- package/dist/types/browser/src/proofs/testing.d.ts +36 -0
- package/dist/types/browser/src/proofs/verify.d.ts +23 -0
- package/dist/types/browser/src/shared/mints.d.ts +50 -0
- package/dist/types/core/src/appBundle.d.ts +173 -0
- package/dist/types/core/src/appStatements.d.ts +142 -0
- package/dist/types/core/src/appStore.d.ts +133 -0
- package/dist/types/core/src/appUpdates.d.ts +88 -0
- package/dist/types/core/src/atprotoIdentity.d.ts +49 -0
- package/dist/types/core/src/atprotoRepo.d.ts +101 -0
- package/dist/types/core/src/avatar.d.ts +19 -0
- package/dist/types/core/src/bip322.d.ts +57 -0
- package/dist/types/core/src/bitcoinAddress.d.ts +5 -0
- package/dist/types/core/src/bitcoinMessage.d.ts +15 -0
- package/dist/types/core/src/bitcoinScript.d.ts +69 -0
- package/dist/types/core/src/bolt11.d.ts +30 -0
- package/dist/types/core/src/bytes.d.ts +11 -0
- package/dist/types/core/src/callSignal.d.ts +232 -0
- package/dist/types/core/src/canonicalJson.d.ts +22 -0
- package/dist/types/core/src/capsRecord.d.ts +234 -0
- package/dist/types/core/src/catchUp.d.ts +45 -0
- package/dist/types/core/src/chatFiles.d.ts +271 -0
- package/dist/types/core/src/clockWatch.d.ts +72 -0
- package/dist/types/core/src/communityRendezvous.d.ts +113 -0
- package/dist/types/core/src/crypto.d.ts +10 -0
- package/dist/types/core/src/datalink.d.ts +187 -0
- package/dist/types/core/src/deviceInvite.d.ts +51 -0
- package/dist/types/core/src/deviceLink.d.ts +70 -0
- package/dist/types/core/src/dhtDelivery.d.ts +407 -0
- package/dist/types/core/src/dhtFiles.d.ts +46 -0
- package/dist/types/core/src/did.d.ts +134 -0
- package/dist/types/core/src/didDht.d.ts +155 -0
- package/dist/types/core/src/directPath.d.ts +63 -0
- package/dist/types/core/src/dns.d.ts +41 -0
- package/dist/types/core/src/domainProofs.d.ts +88 -0
- package/dist/types/core/src/engineErrors.d.ts +91 -0
- package/dist/types/core/src/enroll.d.ts +98 -0
- package/dist/types/core/src/files.d.ts +73 -0
- package/dist/types/core/src/forwards.d.ts +12 -0
- package/dist/types/core/src/frames.d.ts +211 -0
- package/dist/types/core/src/ghostlink.d.ts +1532 -0
- package/dist/types/core/src/groupCommits.d.ts +103 -0
- package/dist/types/core/src/groupCommunity.d.ts +720 -0
- package/dist/types/core/src/groupCrypto.d.ts +60 -0
- package/dist/types/core/src/groupEdits.d.ts +67 -0
- package/dist/types/core/src/groupEntry.d.ts +61 -0
- package/dist/types/core/src/groupFiles.d.ts +106 -0
- package/dist/types/core/src/groupHubs.d.ts +61 -0
- package/dist/types/core/src/groupMentions.d.ts +27 -0
- package/dist/types/core/src/groupMeta.d.ts +162 -0
- package/dist/types/core/src/groupSession.d.ts +728 -0
- package/dist/types/core/src/groupSignals.d.ts +167 -0
- package/dist/types/core/src/groupTyping.d.ts +56 -0
- package/dist/types/core/src/groupWake.d.ts +68 -0
- package/dist/types/core/src/handoff.d.ts +255 -0
- package/dist/types/core/src/http.d.ts +125 -0
- package/dist/types/core/src/identity.d.ts +17 -0
- package/dist/types/core/src/identityProofs.d.ts +243 -0
- package/dist/types/core/src/identityTimeline.d.ts +72 -0
- package/dist/types/core/src/image.d.ts +33 -0
- package/dist/types/core/src/index.d.ts +100 -0
- package/dist/types/core/src/invite.d.ts +128 -0
- package/dist/types/core/src/link.d.ts +353 -0
- package/dist/types/core/src/linkPreview.d.ts +60 -0
- package/dist/types/core/src/linkTrace.d.ts +12 -0
- package/dist/types/core/src/lnurl.d.ts +99 -0
- package/dist/types/core/src/messageTime.d.ts +28 -0
- package/dist/types/core/src/miniApp.d.ts +146 -0
- package/dist/types/core/src/pairedApps.d.ts +151 -0
- package/dist/types/core/src/pairedCalls.d.ts +59 -0
- package/dist/types/core/src/pairedCapabilities.d.ts +101 -0
- package/dist/types/core/src/pairedEdits.d.ts +83 -0
- package/dist/types/core/src/pairedFiles.d.ts +30 -0
- package/dist/types/core/src/pairedHttp.d.ts +15 -0
- package/dist/types/core/src/pairedSession.d.ts +163 -0
- package/dist/types/core/src/pairedSignal.d.ts +17 -0
- package/dist/types/core/src/pairedTransports.d.ts +76 -0
- package/dist/types/core/src/pairedTyping.d.ts +130 -0
- package/dist/types/core/src/pairedWake.d.ts +109 -0
- package/dist/types/core/src/pairingProgress.d.ts +107 -0
- package/dist/types/core/src/paymentIntent.d.ts +111 -0
- package/dist/types/core/src/paymentUri.d.ts +34 -0
- package/dist/types/core/src/payments.d.ts +97 -0
- package/dist/types/core/src/peerProofs.d.ts +98 -0
- package/dist/types/core/src/pins.d.ts +73 -0
- package/dist/types/core/src/pkarr.d.ts +48 -0
- package/dist/types/core/src/pkdns.d.ts +35 -0
- package/dist/types/core/src/pubkyProofs.d.ts +25 -0
- package/dist/types/core/src/pubkyRing.d.ts +21 -0
- package/dist/types/core/src/reactions.d.ts +108 -0
- package/dist/types/core/src/records.d.ts +89 -0
- package/dist/types/core/src/relay.d.ts +459 -0
- package/dist/types/core/src/relayBreaker.d.ts +99 -0
- package/dist/types/core/src/replies.d.ts +41 -0
- package/dist/types/core/src/services.d.ts +35 -0
- package/dist/types/core/src/setUpdate.d.ts +53 -0
- package/dist/types/core/src/signal.d.ts +53 -0
- package/dist/types/core/src/signer.d.ts +13 -0
- package/dist/types/core/src/sparkAddress.d.ts +37 -0
- package/dist/types/core/src/sshsig.d.ts +74 -0
- package/dist/types/core/src/statusCards.d.ts +253 -0
- package/dist/types/core/src/storeForward.d.ts +144 -0
- package/dist/types/core/src/text.d.ts +20 -0
- package/dist/types/core/src/transport.d.ts +158 -0
- package/dist/types/core/src/transportSwitch.d.ts +160 -0
- package/dist/types/core/src/turnRead.d.ts +145 -0
- package/dist/types/core/src/turnRecord.d.ts +165 -0
- package/dist/types/core/src/version.d.ts +9 -0
- package/dist/types/core/src/video.d.ts +44 -0
- package/dist/types/core/src/voice.d.ts +88 -0
- package/dist/types/core/src/webPush.d.ts +58 -0
- package/dist/types/sdk/src/app.d.ts +23 -0
- package/dist/types/sdk/src/core.d.ts +7 -0
- package/dist/types/sdk/src/fakes.d.ts +6 -0
- package/dist/types/sdk/src/index.d.ts +26 -0
- package/dist/types/sdk/src/testing.d.ts +7 -0
- package/dist/types-DvtCy3WB.js +99 -0
- package/dist/types-DvtCy3WB.js.map +1 -0
- package/dist/verify-RjMx7eW6.js +106 -0
- package/dist/verify-RjMx7eW6.js.map +1 -0
- package/package.json +70 -4
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* How far ahead of this device's clock a number a peer made from its clock may be (a pin's number, a status card's
|
|
3
|
+
* times): clocks drift, but a time past this is the peer's choice, not its clock.
|
|
4
|
+
*/
|
|
5
|
+
export declare const MESSAGE_CLOCK_SKEW_MS: number;
|
|
6
|
+
/**
|
|
7
|
+
* The time a line of a group's history is kept under (a membership change, a rename): what its commit says, but at
|
|
8
|
+
* most `MESSAGE_CLOCK_SKEW_MS` past this clock, and now when it is not a positive number. Messages do not use it:
|
|
9
|
+
* they are placed where they arrive (below).
|
|
10
|
+
*/
|
|
11
|
+
export declare function receivedTimestamp(ts: number, now?: number): number;
|
|
12
|
+
/** The time a sender says, as it is kept: a positive time a date can hold, or nothing. */
|
|
13
|
+
export declare function claimedTime(ts: unknown): number | undefined;
|
|
14
|
+
/**
|
|
15
|
+
* The place of a row stored now: this clock, and past the last place given in its chat, so rows that come in the
|
|
16
|
+
* same millisecond (a hold pickup, a group's catch-up) keep the order they came in.
|
|
17
|
+
*/
|
|
18
|
+
export declare function arrivalKey(now: number, last?: number): number;
|
|
19
|
+
/** The time a message shows: what its sender said, never later than when it came. A row of mine shows its own time. */
|
|
20
|
+
export declare function shownTime(message: {
|
|
21
|
+
timestamp: number;
|
|
22
|
+
sentAt?: number;
|
|
23
|
+
}): number;
|
|
24
|
+
/**
|
|
25
|
+
* When something a peer dated happened (an edit), for this device: what the peer says, now at the latest, and now
|
|
26
|
+
* when it says nothing a date can hold.
|
|
27
|
+
*/
|
|
28
|
+
export declare function heardTime(ts: unknown, now?: number): number;
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The mini-app API: what an app in the runner's sandbox can ask the client's broker for, and nothing more.
|
|
3
|
+
*
|
|
4
|
+
* Matches the broker table of WISP 1200 (docs/wisps/1200-marketplace.md, "The runner and the broker"). Types, limits and refusal codes only, with no imports: the broker (apps/ui) and
|
|
5
|
+
* the apps (apps/mini/*) import this one module, so neither side can drift from the other, and app developers get it as
|
|
6
|
+
* `@ghostlytools/sdk/app`. It is imported as `@ghostly/core/miniApp`, outside the
|
|
7
|
+
* core barrel, because apps bundle it into their single HTML file.
|
|
8
|
+
*/
|
|
9
|
+
/** A JSON value: what `storage` keeps and what `chat.send` carries. */
|
|
10
|
+
export type MiniAppJson = null | boolean | number | string | MiniAppJson[] | {
|
|
11
|
+
[key: string]: MiniAppJson;
|
|
12
|
+
};
|
|
13
|
+
/** `ghostly.context()`. */
|
|
14
|
+
export interface MiniAppContext {
|
|
15
|
+
/** This app's version (its manifest's `version`). */
|
|
16
|
+
version: string;
|
|
17
|
+
/** Opened in a chat (true) or alone (false). */
|
|
18
|
+
inChat: boolean;
|
|
19
|
+
/** The same app on the contact's side, while it is open there; null when it is not. */
|
|
20
|
+
peer: {
|
|
21
|
+
version: string;
|
|
22
|
+
} | null;
|
|
23
|
+
/** The person's display name in this chat, only with the `name` permission. */
|
|
24
|
+
name?: string;
|
|
25
|
+
/** The client's theme, so the app can match it. An app may fall back to `prefers-color-scheme` when it is missing. */
|
|
26
|
+
theme?: "light" | "dark";
|
|
27
|
+
/** The client's language (BCP 47, for example "pt-BR"). An app may fall back to `navigator.language` when it is missing. */
|
|
28
|
+
locale?: string;
|
|
29
|
+
}
|
|
30
|
+
/** `chat.peer`: the peer opened the app (again, or in another version) or closed it. */
|
|
31
|
+
export type MiniAppPeerEvent = {
|
|
32
|
+
open: true;
|
|
33
|
+
version: string;
|
|
34
|
+
} | {
|
|
35
|
+
open: false;
|
|
36
|
+
};
|
|
37
|
+
/** `window.ghostly` inside the sandbox. */
|
|
38
|
+
export interface MiniAppApi {
|
|
39
|
+
context(): Promise<MiniAppContext>;
|
|
40
|
+
/** The bytes of a file of the bundle. */
|
|
41
|
+
file(path: string): Promise<ArrayBuffer>;
|
|
42
|
+
/** The app's storage in its scope: this app in this chat, or this app alone. */
|
|
43
|
+
storage: {
|
|
44
|
+
/** The value, or undefined when the key is not set. */
|
|
45
|
+
get(key: string): Promise<MiniAppJson | undefined>;
|
|
46
|
+
set(key: string, value: MiniAppJson): Promise<void>;
|
|
47
|
+
delete(key: string): Promise<void>;
|
|
48
|
+
keys(): Promise<string[]>;
|
|
49
|
+
};
|
|
50
|
+
chat: {
|
|
51
|
+
/** One `apps/1` data frame to the same app on the contact's side. Refused unless the chat is live and the peer has the app open. */
|
|
52
|
+
send(value: MiniAppJson): Promise<void>;
|
|
53
|
+
/** A data frame from the peer, as the peer's app sent it: untrusted. Returns a function that removes the listener. */
|
|
54
|
+
on(event: "message", listener: (data: MiniAppJson) => void): () => void;
|
|
55
|
+
on(event: "peer", listener: (peer: MiniAppPeerEvent) => void): () => void;
|
|
56
|
+
};
|
|
57
|
+
/** Ends the app. */
|
|
58
|
+
close(): Promise<void>;
|
|
59
|
+
}
|
|
60
|
+
/** 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";
|
|
62
|
+
/** A request from the app: `{id, type, args}`. The broker refuses an unknown `type`. */
|
|
63
|
+
export interface MiniAppRequest {
|
|
64
|
+
id: number;
|
|
65
|
+
type: MiniAppRequestType;
|
|
66
|
+
args: MiniAppJson[];
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Every code a refused request answers with (WISP 1200, "The runner and the broker"). In the sandbox every failed
|
|
70
|
+
* `ghostly.*` call rejects with an `Error` whose `message` is one of these codes; `miniAppErrorCode` reads it back. The
|
|
71
|
+
* runner turns its own failures (no answer from the client, a lost broker) into `failed`, and arguments that are not
|
|
72
|
+
* JSON into `bad-request`.
|
|
73
|
+
*
|
|
74
|
+
* - `bad-key`: a storage key that is not a string of 1 to 256 bytes.
|
|
75
|
+
* - `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.
|
|
77
|
+
* - `failed`: anything else; the client's own words never reach the app.
|
|
78
|
+
* - `full`: a storage write would take the scope past 5 MiB (each key counts 128 bytes beside its own and its value's),
|
|
79
|
+
* so the app can make room.
|
|
80
|
+
* - `no-file`: the bundle has no such file.
|
|
81
|
+
* - `not-allowed`: `chat.send` without the `chat` permission, or with the app opened alone.
|
|
82
|
+
* - `not-open`: `chat.send` before this side's chat has the app open.
|
|
83
|
+
* - `offline`: `chat.send` while the chat's session is not live. Nothing is kept to send later.
|
|
84
|
+
* - `peer-closed`: `chat.send` while the contact has not opened the app (or its client does not offer `apps/1`).
|
|
85
|
+
* - `stopped`: a store removed or the publisher revoked the version running.
|
|
86
|
+
* - `too-fast`: past 50 requests a second, or past 48 `chat.send` frames a second.
|
|
87
|
+
* - `too-large`: a request, a stored value or a `chat.send` value past its bound (`MINI_APP_LIMITS`).
|
|
88
|
+
* - `unknown-type`: a request `type` the broker does not answer.
|
|
89
|
+
*
|
|
90
|
+
* A later client may add a code: treat one you do not know as `failed`.
|
|
91
|
+
*/
|
|
92
|
+
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"];
|
|
93
|
+
export type MiniAppErrorCode = typeof MINI_APP_ERROR_CODES[number];
|
|
94
|
+
/** The code of a refused `ghostly.*` call (the rejection's `Error`), or null for anything that is not one. */
|
|
95
|
+
export declare function miniAppErrorCode(error: unknown): MiniAppErrorCode | null;
|
|
96
|
+
/**
|
|
97
|
+
* The broker's answer to one request. `value` is JSON, or an `ArrayBuffer` for `file` on the port (web, extension). On
|
|
98
|
+
* Desktop `app_broker` answers `file` with `bytes` instead, the file in base64, and the runner hands the app an
|
|
99
|
+
* `ArrayBuffer` either way.
|
|
100
|
+
*
|
|
101
|
+
* `error` is one of `MINI_APP_ERROR_CODES` from this client; a later client may send a code this list does not have yet,
|
|
102
|
+
* which an app reads as `failed`.
|
|
103
|
+
*/
|
|
104
|
+
export type MiniAppAnswer = {
|
|
105
|
+
id: number;
|
|
106
|
+
ok: true;
|
|
107
|
+
value?: MiniAppJson | ArrayBuffer;
|
|
108
|
+
} | {
|
|
109
|
+
id: number;
|
|
110
|
+
ok: true;
|
|
111
|
+
bytes: string;
|
|
112
|
+
} | {
|
|
113
|
+
id: number;
|
|
114
|
+
ok: false;
|
|
115
|
+
error: MiniAppErrorCode | (string & {});
|
|
116
|
+
};
|
|
117
|
+
/** An event from the broker. */
|
|
118
|
+
export type MiniAppEvent = {
|
|
119
|
+
event: "chat.message";
|
|
120
|
+
data: MiniAppJson;
|
|
121
|
+
} | {
|
|
122
|
+
event: "chat.peer";
|
|
123
|
+
data: MiniAppPeerEvent;
|
|
124
|
+
};
|
|
125
|
+
/** Limits the broker enforces (and an app can plan for). */
|
|
126
|
+
export declare const MINI_APP_LIMITS: {
|
|
127
|
+
/** One request, serialized. */
|
|
128
|
+
readonly requestBytes: number;
|
|
129
|
+
/** Requests per second, per app. */
|
|
130
|
+
readonly requestsPerSecond: 50;
|
|
131
|
+
/**
|
|
132
|
+
* Bytes of `file` answers per second, per app: a whole bundle's worth. A read that starts under it is answered whole;
|
|
133
|
+
* past it `file` is refused with `too-fast` until the second has gone.
|
|
134
|
+
*/
|
|
135
|
+
readonly fileBytesPerSecond: number;
|
|
136
|
+
/** A storage key, UTF-8. */
|
|
137
|
+
readonly storageKeyBytes: 256;
|
|
138
|
+
/** One stored JSON value, serialized. */
|
|
139
|
+
readonly storageValueBytes: number;
|
|
140
|
+
/** Counted for each stored key beside its own bytes and its value's: what keeping the key costs the device. */
|
|
141
|
+
readonly storageRowBytes: 128;
|
|
142
|
+
/** Everything an app keeps in one scope (per app and per chat, or alone): each key, its value and `storageRowBytes`. */
|
|
143
|
+
readonly storageScopeBytes: number;
|
|
144
|
+
/** One `chat.send` value, serialized: the `paired-app` data cap (decision D5 of the plan). */
|
|
145
|
+
readonly chatDataBytes: number;
|
|
146
|
+
};
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Mini-apps talking in a 1:1 chat (WISP 1200 § In a chat: `apps/1`): the same app on both sides sends JSON to the
|
|
3
|
+
* other over the live session, in one frame with three forms.
|
|
4
|
+
*
|
|
5
|
+
* {"t":"paired-app","a":"<chat app id>","o":"open","v":"1.2.0"}
|
|
6
|
+
* {"t":"paired-app","a":"<chat app id>","o":"close"}
|
|
7
|
+
* {"t":"paired-app","a":"<chat app id>","d":<JSON value>}
|
|
8
|
+
*
|
|
9
|
+
* It needs `apps/1` in `paired-capabilities` on both sides. Live only: never on the DHT, never held, never queued for
|
|
10
|
+
* later; while the session is not live a send fails with `offline`. An `open` goes when the person opens the app in
|
|
11
|
+
* the chat, again on an update, and again on every session that comes back while the app is open. The receiver
|
|
12
|
+
* enforces the limits (the sender's client may be the attacker): at most `APP_DATA_MAX_BYTES` of data, at most
|
|
13
|
+
* `APP_RATE_LIMIT` frames a second per app, data only for an app open on both sides, at most `APP_PEER_OPEN_MAX`
|
|
14
|
+
* apps the peer has open, and nothing unless both sides offer `apps/1`.
|
|
15
|
+
*
|
|
16
|
+
* The chat app id names one app in one chat: the first 16 bytes of HMAC-SHA-256 keyed by the two pinned participation
|
|
17
|
+
* keys over the app reference `<publisher key in z-base32>/<name>`. One app's id differs in each chat, so ids cannot
|
|
18
|
+
* be matched across a person's chats; it travels only inside the encrypted session.
|
|
19
|
+
*/
|
|
20
|
+
export declare const APP_FRAME = "paired-app";
|
|
21
|
+
/** The largest `d`, as compact UTF-8 JSON. The session's 60 KiB cap on any frame still holds above it. */
|
|
22
|
+
export declare const APP_DATA_MAX_BYTES: number;
|
|
23
|
+
/** Frames a receiver takes per app per `APP_RATE_WINDOW_MS`; the rest are dropped unread. */
|
|
24
|
+
export declare const APP_RATE_LIMIT = 50;
|
|
25
|
+
export declare const APP_RATE_WINDOW_MS = 1000;
|
|
26
|
+
/** Data frames a sender sends per app per window: under the receiver's limit, so an `open` or `close` always fits. */
|
|
27
|
+
export declare const APP_SEND_LIMIT: number;
|
|
28
|
+
/** Distinct apps the peer may have open on one session; an `open` for one more is dropped. */
|
|
29
|
+
export declare const APP_PEER_OPEN_MAX = 16;
|
|
30
|
+
/** The longest version an `open` carries. */
|
|
31
|
+
export declare const APP_VERSION_MAX = 64;
|
|
32
|
+
/**
|
|
33
|
+
* How long the peer's open apps are held when its session ends or is replaced (a transport switch, a resume, a
|
|
34
|
+
* re-dial), before they are taken as closed. A new session within it says `open` again for each: the app hears that
|
|
35
|
+
* open (and catches up), never a `close` in between. Past it, each still held is closed with `offline`.
|
|
36
|
+
*/
|
|
37
|
+
export declare const APP_RESUME_GRACE_MS = 10000;
|
|
38
|
+
/** Why a send did not go. */
|
|
39
|
+
export type AppSendError =
|
|
40
|
+
/** This side has not opened the app in this chat. */
|
|
41
|
+
"not-open"
|
|
42
|
+
/** The value is over `APP_DATA_MAX_BYTES` as JSON (or is not JSON). */
|
|
43
|
+
| "too-large"
|
|
44
|
+
/** The session is not live. Nothing is kept to send later. */
|
|
45
|
+
| "offline"
|
|
46
|
+
/** The peer has not opened the app on this session, or its app does not offer `apps/1`. */
|
|
47
|
+
| "peer-closed"
|
|
48
|
+
/** Over `APP_SEND_LIMIT` data frames in the window for this app. */
|
|
49
|
+
| "too-fast";
|
|
50
|
+
export type AppFrame = {
|
|
51
|
+
t: typeof APP_FRAME;
|
|
52
|
+
a: string;
|
|
53
|
+
o: "open";
|
|
54
|
+
v: string;
|
|
55
|
+
} | {
|
|
56
|
+
t: typeof APP_FRAME;
|
|
57
|
+
a: string;
|
|
58
|
+
o: "close";
|
|
59
|
+
} | {
|
|
60
|
+
t: typeof APP_FRAME;
|
|
61
|
+
a: string;
|
|
62
|
+
d: unknown;
|
|
63
|
+
};
|
|
64
|
+
/**
|
|
65
|
+
* What the peer said about one app, as the engine passes it on. `close` with `offline` is not a frame: the session
|
|
66
|
+
* ended (or `apps/1` stopped being agreed) while the peer had the app open.
|
|
67
|
+
*/
|
|
68
|
+
export type AppFrameEvent = {
|
|
69
|
+
app: string;
|
|
70
|
+
o: "open";
|
|
71
|
+
v: string;
|
|
72
|
+
} | {
|
|
73
|
+
app: string;
|
|
74
|
+
o: "close";
|
|
75
|
+
offline?: true;
|
|
76
|
+
} | {
|
|
77
|
+
app: string;
|
|
78
|
+
d: unknown;
|
|
79
|
+
};
|
|
80
|
+
/** A chat app id as it is on the wire: 22 base64url characters (16 bytes, no padding). */
|
|
81
|
+
export declare function isChatAppId(value: unknown): value is string;
|
|
82
|
+
/** A version an `open` may carry: semantic versioning, at most `APP_VERSION_MAX` characters. */
|
|
83
|
+
export declare function isAppVersion(value: unknown): value is string;
|
|
84
|
+
/**
|
|
85
|
+
* The chat app id of `ref` in the chat between these two participation keys (raw, 32 bytes each, in either order):
|
|
86
|
+
* HMAC-SHA-256 keyed by SHA-256(`ghostly-apps/1`, 0x00, the lower key, the higher key), over the UTF-8 reference;
|
|
87
|
+
* its first 16 bytes, base64url without padding.
|
|
88
|
+
*/
|
|
89
|
+
export declare function chatAppId(keyA: Uint8Array, keyB: Uint8Array, ref: string): string;
|
|
90
|
+
/** The size of a value as compact UTF-8 JSON; Infinity when it is not JSON (undefined, a function, a cycle, a BigInt). */
|
|
91
|
+
export declare function appDataBytes(value: unknown): number;
|
|
92
|
+
export declare function appOpenFrame(app: string, version: string): AppFrame;
|
|
93
|
+
export declare function appCloseFrame(app: string): AppFrame;
|
|
94
|
+
export declare function appDataFrame(app: string, data: unknown): AppFrame;
|
|
95
|
+
/** Why a reader refuses a `paired-app` frame (the vectors' `refusal`). */
|
|
96
|
+
export type AppFrameRefusal = "not-app" | "bad-a" | "o-and-d" | "no-o-or-d" | "too-large" | "unknown-o" | "bad-v";
|
|
97
|
+
/**
|
|
98
|
+
* A `paired-app` frame as the peer sent it, or why a reader must refuse it: no valid `a` (22 base64url characters),
|
|
99
|
+
* both or neither of `o` and `d`, an unknown `o`, an `open` without a valid `v`, or a `d` over `APP_DATA_MAX_BYTES`.
|
|
100
|
+
* Other keys are ignored, so a later version can add some.
|
|
101
|
+
*/
|
|
102
|
+
export declare function readAppFrame(frame: Record<string, unknown>): {
|
|
103
|
+
ok: true;
|
|
104
|
+
frame: AppFrame;
|
|
105
|
+
} | {
|
|
106
|
+
ok: false;
|
|
107
|
+
refusal: AppFrameRefusal;
|
|
108
|
+
};
|
|
109
|
+
/** A `paired-app` frame as the peer sent it, or null when a reader must refuse it (`readAppFrame` says why). */
|
|
110
|
+
export declare function parseAppFrame(frame: Record<string, unknown>): AppFrame | null;
|
|
111
|
+
/**
|
|
112
|
+
* The apps of one chat on its live sessions. `open` (this side's apps, by chat app id, with their versions) lasts
|
|
113
|
+
* across sessions, so each new one says `open` again; what the peer has open lasts one session.
|
|
114
|
+
*/
|
|
115
|
+
export declare class AppSessions {
|
|
116
|
+
readonly open: Map<string, string>;
|
|
117
|
+
private readonly now;
|
|
118
|
+
private readonly peer;
|
|
119
|
+
/** What the peer had open on a session that ended, held for `APP_RESUME_GRACE_MS` until it says so again. */
|
|
120
|
+
private readonly held;
|
|
121
|
+
private received;
|
|
122
|
+
private sent;
|
|
123
|
+
constructor(open?: Map<string, string>, now?: () => number);
|
|
124
|
+
/** The peer has this app open on this session, at this version. */
|
|
125
|
+
peerVersion(app: string): string | undefined;
|
|
126
|
+
/** The apps the peer has open on this session. */
|
|
127
|
+
get peerOpen(): ReadonlyMap<string, string>;
|
|
128
|
+
/**
|
|
129
|
+
* A `paired-app` frame from the peer, on a session where both sides offer `apps/1`. Counted before it is read; the
|
|
130
|
+
* event to pass on, or null when it was dropped (malformed, over the rate, a data frame for an app not open on both
|
|
131
|
+
* sides, an `open` past `APP_PEER_OPEN_MAX`, a `close` of an app the peer did not have open).
|
|
132
|
+
*/
|
|
133
|
+
receive(frame: Record<string, unknown>): AppFrameEvent | null;
|
|
134
|
+
/** Whether a data frame for `app` may go now, the session being live with `apps/1` agreed; counted when it may. */
|
|
135
|
+
canSend(app: string, data: unknown): AppSendError | null;
|
|
136
|
+
/**
|
|
137
|
+
* The session ended, or `apps/1` is no longer agreed: what the peer had open is gone, and each such app hears a
|
|
138
|
+
* `close` with `offline`. This side's open apps stay, and say `open` again on the next session.
|
|
139
|
+
*/
|
|
140
|
+
sessionEnded(): AppFrameEvent[];
|
|
141
|
+
/**
|
|
142
|
+
* The session ended or was replaced, and another may follow at once: what the peer had open is held, not closed (no
|
|
143
|
+
* event now). Nothing is sent to a held app; an `open` on the next session takes it back, a `close` closes it, and
|
|
144
|
+
* `heldExpired` closes the rest once `APP_RESUME_GRACE_MS` has passed.
|
|
145
|
+
*/
|
|
146
|
+
sessionSuspended(): void;
|
|
147
|
+
/** Whether any of the peer's apps is held, waiting for its next session. */
|
|
148
|
+
get holding(): boolean;
|
|
149
|
+
/** The grace is over: each app still held is closed, with `offline`. */
|
|
150
|
+
heldExpired(): AppFrameEvent[];
|
|
151
|
+
}
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Call signaling on a paired session (`calls/1`, WISP 601): the same compact signals a compatibility chat
|
|
3
|
+
* keeps in its `_call` record, carried as one frame each on the authenticated session instead:
|
|
4
|
+
*
|
|
5
|
+
* {"t":"paired-call","s":"<signal>"}
|
|
6
|
+
*
|
|
7
|
+
* The media is not on this session: it runs on a WebRTC connection of its own, whose DTLS fingerprint the
|
|
8
|
+
* offer and answer carry, so whatever carries the chat (WebRTC, Iroh, HyperDHT) the media is bound to the
|
|
9
|
+
* contact this session authenticated. Nothing about a call is ever published on the DHT.
|
|
10
|
+
*/
|
|
11
|
+
export declare const PAIRED_CALL_FRAME = "paired-call";
|
|
12
|
+
/** A compact offer with the eight candidates `parseCallSignal` accepts stays well under this. */
|
|
13
|
+
export declare const MAX_PAIRED_CALL_SIGNAL = 8192;
|
|
14
|
+
export interface PairedCallFrame {
|
|
15
|
+
t: typeof PAIRED_CALL_FRAME;
|
|
16
|
+
s: string;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* The signal a `paired-call` frame carries, or null when it is not a well-formed one. It came on a live session, now:
|
|
20
|
+
* that is when it was heard (`heardCallSignal`), whatever time its sender's clock gave it.
|
|
21
|
+
*/
|
|
22
|
+
export declare function parsePairedCallFrame(frame: Record<string, unknown>, now?: number): string | null;
|
|
23
|
+
/**
|
|
24
|
+
* This side's latest call signal. What could not go (the session dropped between two frames) goes on the
|
|
25
|
+
* next session while it is still fresh, as the `_call` record of a compatibility chat is read on the next
|
|
26
|
+
* poll; clearing it (after a hang-up, or a call that never started) means there is nothing left to say.
|
|
27
|
+
*/
|
|
28
|
+
export declare class PairedCalls {
|
|
29
|
+
private readonly now;
|
|
30
|
+
private latest;
|
|
31
|
+
/** When this side last said anything about a call, a clear included. */
|
|
32
|
+
private saidAt;
|
|
33
|
+
/** The contact's latest signal on a session: its kind, when it came, and the time its sender gave it. */
|
|
34
|
+
private peer;
|
|
35
|
+
constructor(now?: () => number);
|
|
36
|
+
/** A new signal to send (null clears it). Returns the frame to send now, if any. */
|
|
37
|
+
set(signal: string | null): PairedCallFrame | null;
|
|
38
|
+
/**
|
|
39
|
+
* A signal the contact sent (one `parsePairedCallFrame` took). False when it is not newer than the last one heard
|
|
40
|
+
* from the contact on this chat: the contact's app sends its latest signal again on each new session while it is
|
|
41
|
+
* fresh (`pending`), and one already heard is not news. Handed on again, an answer to an earlier call that names no
|
|
42
|
+
* offer (an app up to 1.0.2) was taken for the call placed since, whose connection it does not fit.
|
|
43
|
+
*/
|
|
44
|
+
heard(signal: string): boolean;
|
|
45
|
+
/**
|
|
46
|
+
* Whether a call is on, as the latest signal of either side says: an answer or a picture change, or an offer still
|
|
47
|
+
* fresh enough to ring. A hang-up, a clear, or an offer nobody answered in time ends it. Read by kind, as `hangUp` is:
|
|
48
|
+
* the media runs on a connection of its own, so an hour-long call shows nothing else on the session.
|
|
49
|
+
*/
|
|
50
|
+
get on(): boolean;
|
|
51
|
+
/**
|
|
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.
|
|
55
|
+
*/
|
|
56
|
+
hangUp(): PairedCallFrame | null;
|
|
57
|
+
/** On a new session that carries calls: the latest signal again, if it is still fresh enough to act on. */
|
|
58
|
+
pending(): PairedCallFrame | null;
|
|
59
|
+
}
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Capabilities a paired session announces once it is ready (WISP 03, 401): what this app does on this
|
|
3
|
+
* session beyond what the handshake offer carries. Apps before 0.5 accept at most 16 entries in the offer's
|
|
4
|
+
* `capabilities`, and a full offer is already there, so these travel in one frame on the authenticated
|
|
5
|
+
* session instead, the way `paired-payments` and `paired-groups` do:
|
|
6
|
+
*
|
|
7
|
+
* {"t":"paired-capabilities","c":["calls/1","services/1","files/3","typing/1","react/1","edit/1"]}
|
|
8
|
+
*
|
|
9
|
+
* Each side sends it on every ready session, and again whenever what it offers changes. Something is on
|
|
10
|
+
* only while both sides list it; a peer that never sends the frame (an older app) offers nothing here.
|
|
11
|
+
* The frame carries no message id, so older apps drop it.
|
|
12
|
+
*/
|
|
13
|
+
import type { DeviceCapability } from "./deviceLink.js";
|
|
14
|
+
/** Voice and video calls: `paired-call` signals on this session, media on a WebRTC connection of its own (WISP 601). */
|
|
15
|
+
export declare const CALLS_CAPABILITY = "calls/1";
|
|
16
|
+
/** Shared local web apps: `paired-services` and `ph` HTTP frames on this session (WISP 701). */
|
|
17
|
+
export declare const SERVICES_CAPABILITY = "services/1";
|
|
18
|
+
/**
|
|
19
|
+
* Files of any size (WISP 501 rev 0.3): offered and accepted, many chunks in flight, resumed from the last
|
|
20
|
+
* confirmed byte, checked by digest (`pf-offer` … frames, `chatFiles.ts`). Without it, files/2 and 100 MiB.
|
|
21
|
+
*/
|
|
22
|
+
export declare const FILES_CAPABILITY = "files/3";
|
|
23
|
+
/** The typing indicator: `paired-typing` frames on this session, 1:1 chats only (WISP 401 § Typing, `pairedTyping.ts`). */
|
|
24
|
+
export declare const TYPING_CAPABILITY = "typing/1";
|
|
25
|
+
/** Reactions to messages: `paired-reaction` frames on this session, 1:1 chats only (WISP 401 § Reactions, `reactions.ts`). */
|
|
26
|
+
export declare const REACTIONS_CAPABILITY = "react/1";
|
|
27
|
+
/** Editing sent texts: `paired-edit` frames on this session, 1:1 chats only (WISP 401 § Edits, `pairedEdits.ts`). */
|
|
28
|
+
export declare const EDIT_CAPABILITY = "edit/1";
|
|
29
|
+
/** Wake-up push: `paired-wake` frames on this session, 1:1 chats only (WISP 401 § Wake-up push, `pairedWake.ts`). */
|
|
30
|
+
export declare const WAKE_SESSION_CAPABILITY = "wake/1";
|
|
31
|
+
/** A pinned message: `paired-pin` frames on this session, 1:1 chats only (WISP 401 § Pinned message, `pins.ts`). */
|
|
32
|
+
export declare const PIN_CAPABILITY = "pin/1";
|
|
33
|
+
/**
|
|
34
|
+
* Status cards: this app shows a message's card (`sc`) and takes a card message's edits past the text's 100, which an
|
|
35
|
+
* older app would drop (WISP 405 · Status Cards, `statusCards.ts`). A card itself needs nothing: older apps show its text.
|
|
36
|
+
*/
|
|
37
|
+
export declare const STATUS_CARD_CAPABILITY = "status-card/1";
|
|
38
|
+
/**
|
|
39
|
+
* Message buttons: this app shows a message's buttons (a card of kind `buttons`) and presses them with a reply naming
|
|
40
|
+
* the button (WISP 406 · Message Buttons). Nothing is gated on it: an older app shows the text and sends replies, and
|
|
41
|
+
* a press reads as an ordinary reply there. It tells a bot whether its contact can press at all.
|
|
42
|
+
*/
|
|
43
|
+
export declare const BUTTONS_CAPABILITY = "buttons/1";
|
|
44
|
+
/**
|
|
45
|
+
* A session live on a relayed transport while a direct one ranks first, with nobody's choice behind it, moves to the
|
|
46
|
+
* direct one once, in place, its signaling on the session (WISP 100 § Back to a quiet contact): what a chat that came
|
|
47
|
+
* back over a relay at once (rather than wait for an offer's answer) needs to end where a direct path would have put
|
|
48
|
+
* it. Both sides must say it: the switch is planned by one and checked by the other. Also in the capability record
|
|
49
|
+
* (WISP 03), so an app back after an absence knows before any session whether a relay can carry it there at once.
|
|
50
|
+
*/
|
|
51
|
+
export declare const UPGRADE_CAPABILITY = "upgrade/1";
|
|
52
|
+
/**
|
|
53
|
+
* Mini-apps in a 1:1 chat: `paired-app` frames on this session, live only (WISP 1200 § In a chat: `apps/1`,
|
|
54
|
+
* `pairedApps.ts`). Offered only while the apps feature is on.
|
|
55
|
+
*/
|
|
56
|
+
export declare const APPS_CAPABILITY = "apps/1";
|
|
57
|
+
/**
|
|
58
|
+
* What only a device link offers (WISP 06, `deviceLink.ts`): the frames between a person's own devices. They are in
|
|
59
|
+
* the type so a device link can announce them, and not in `KNOWN_SESSION_CAPABILITIES`: no chat knows them.
|
|
60
|
+
*/
|
|
61
|
+
export type SessionCapability = DeviceCapability | typeof CALLS_CAPABILITY | typeof SERVICES_CAPABILITY | typeof FILES_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;
|
|
62
|
+
/** Every capability this app knows on a session: what `receive` reports changes of. */
|
|
63
|
+
export declare const KNOWN_SESSION_CAPABILITIES: readonly SessionCapability[];
|
|
64
|
+
export declare const SESSION_CAPABILITIES_FRAME = "paired-capabilities";
|
|
65
|
+
/** The frame that says what this side offers. */
|
|
66
|
+
export declare function sessionCapabilitiesFrame(offered: readonly SessionCapability[]): {
|
|
67
|
+
t: typeof SESSION_CAPABILITIES_FRAME;
|
|
68
|
+
c: string[];
|
|
69
|
+
};
|
|
70
|
+
/**
|
|
71
|
+
* The capabilities a `paired-capabilities` frame lists, or null when it is malformed (then it says nothing,
|
|
72
|
+
* and what the peer said before stands). Identifiers this app does not know are kept: they grant nothing,
|
|
73
|
+
* since only what both sides list is on.
|
|
74
|
+
*/
|
|
75
|
+
export declare function parseSessionCapabilities(frame: Record<string, unknown>): Set<string> | null;
|
|
76
|
+
/** What both sides of one session offer. Reset when the session goes. */
|
|
77
|
+
export declare class SessionCapabilities {
|
|
78
|
+
private readonly offered;
|
|
79
|
+
private peer;
|
|
80
|
+
constructor(offered: () => readonly SessionCapability[]);
|
|
81
|
+
/** The frame to send now: on every ready session, and after what this side offers changed. */
|
|
82
|
+
announcement(): {
|
|
83
|
+
t: typeof SESSION_CAPABILITIES_FRAME;
|
|
84
|
+
c: string[];
|
|
85
|
+
};
|
|
86
|
+
/** This side offers it (whatever the peer says). */
|
|
87
|
+
offers(capability: SessionCapability): boolean;
|
|
88
|
+
/** The peer listed it on this session. False until the peer says anything. */
|
|
89
|
+
peerOffers(capability: SessionCapability): boolean;
|
|
90
|
+
/** The peer has said what it offers on this session. */
|
|
91
|
+
get peerAnnounced(): boolean;
|
|
92
|
+
/** Both sides offer it on this session. */
|
|
93
|
+
agreed(capability: SessionCapability): boolean;
|
|
94
|
+
/**
|
|
95
|
+
* A `paired-capabilities` frame from the peer. Returns the capabilities whose agreement changed, or null
|
|
96
|
+
* when the frame was malformed and ignored.
|
|
97
|
+
*/
|
|
98
|
+
receive(frame: Record<string, unknown>, known?: readonly SessionCapability[]): SessionCapability[] | null;
|
|
99
|
+
/** The session ended: nothing is agreed until the next one says so. */
|
|
100
|
+
reset(): void;
|
|
101
|
+
}
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
import { type LinkPreview } from "./linkPreview.js";
|
|
2
|
+
import { type StatusCard } from "./statusCards.js";
|
|
3
|
+
/**
|
|
4
|
+
* Editing a sent text in a 1:1 chat (WISP 401 § Edits). The sender says the whole new text of one of its own
|
|
5
|
+
* messages, with a sequence number of its own per message, and the contact confirms the number it now shows:
|
|
6
|
+
*
|
|
7
|
+
* {"t":"paired-edit","id":"<the message's wire id>","e":3,"ts":1790000000000,"m":"Done: 12 of 12"}
|
|
8
|
+
* {"t":"paired-edited","id":"<the message's wire id>","e":3}
|
|
9
|
+
*
|
|
10
|
+
* It needs `edit/1` in `paired-capabilities` on both sides. Only the contact's own messages can be edited from its
|
|
11
|
+
* side: the frame comes on the session authenticated with the pinned contact, and the receiver looks the id up among
|
|
12
|
+
* that contact's messages only. The highest `e` wins, whatever order frames arrive in; an edit that is not newer is
|
|
13
|
+
* confirmed and changes nothing. A preview (`pv`, WISP 401 § Link previews) may come with the new text, as with a
|
|
14
|
+
* message. A status card (`sc`, WISP 405 · Status Cards) may come with it too; a card message takes up to
|
|
15
|
+
* `STATUS_CARD_LIMITS.edits` edits, a number past `MAX_EDITS_PER_MESSAGE` holding only with a card. Older apps drop
|
|
16
|
+
* both frames: they have an id, but a `t` they do not know.
|
|
17
|
+
*/
|
|
18
|
+
export declare const EDIT_FRAME = "paired-edit";
|
|
19
|
+
export declare const EDITED_FRAME = "paired-edited";
|
|
20
|
+
/** Edits one message takes; the sender refuses the next one and the receiver ignores a higher number. */
|
|
21
|
+
export declare const MAX_EDITS_PER_MESSAGE = 100;
|
|
22
|
+
/** A sender says at most this many edits per `EDIT_RATE_WINDOW_MS` in one chat; the newest text of each message waits. */
|
|
23
|
+
export declare const EDIT_SEND_LIMIT = 10;
|
|
24
|
+
/** A receiver takes at most this many edit frames per window; the rest are dropped unconfirmed, so they come again. */
|
|
25
|
+
export declare const EDIT_RECEIVE_LIMIT = 30;
|
|
26
|
+
export declare const EDIT_RATE_WINDOW_MS = 10000;
|
|
27
|
+
/** An edit of a message not here yet waits this long for it, at most `EDIT_BUFFER_MAX` of them per chat. */
|
|
28
|
+
export declare const EDIT_BUFFER_MS = 60000;
|
|
29
|
+
export declare const EDIT_BUFFER_MAX = 32;
|
|
30
|
+
/** One edit as it goes on the wire. */
|
|
31
|
+
export interface WireEdit {
|
|
32
|
+
/** The edited message's wire id. */
|
|
33
|
+
id: string;
|
|
34
|
+
/** Its edit number, 1 for the first edit. */
|
|
35
|
+
e: number;
|
|
36
|
+
/** When the sender made the edit (milliseconds). */
|
|
37
|
+
ts: number;
|
|
38
|
+
/** The whole new text. */
|
|
39
|
+
m: string;
|
|
40
|
+
pv?: LinkPreview;
|
|
41
|
+
/** The status card of this version (WISP 405 · Status Cards): a message with a card takes an edit with one. */
|
|
42
|
+
sc?: StatusCard;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* A `paired-edit` frame; the preview is left out when the frame would be too large with it. A card (`sc`) always
|
|
46
|
+
* goes: it is bounded well under what the frame has room for, and it is what a card message is.
|
|
47
|
+
*/
|
|
48
|
+
export declare function editFrame(edit: WireEdit): string;
|
|
49
|
+
/** The frame that confirms edit `e` of message `id`. */
|
|
50
|
+
export declare function editedFrame(id: string, e: number): string;
|
|
51
|
+
/** An edit number a message can have. */
|
|
52
|
+
export declare function validEditNumber(e: unknown): e is number;
|
|
53
|
+
/** A message's new text: not empty, no space around it, within a chat message's bytes. The same on a session and on the DHT. */
|
|
54
|
+
export declare function validEditMessage(m: unknown): m is string;
|
|
55
|
+
/**
|
|
56
|
+
* The edit a `paired-edit` frame says, or null when it is malformed (then it says nothing and is not confirmed). A
|
|
57
|
+
* preview or a card that does not hold is dropped, never the edit; an edit numbered past `MAX_EDITS_PER_MESSAGE`
|
|
58
|
+
* holds only with a card.
|
|
59
|
+
*/
|
|
60
|
+
export declare function parseEditFrame(frame: Record<string, unknown>, now?: number): WireEdit | null;
|
|
61
|
+
/** The confirmation a `paired-edited` frame says, or null when it is malformed. */
|
|
62
|
+
export declare function parseEditedFrame(frame: Record<string, unknown>): {
|
|
63
|
+
id: string;
|
|
64
|
+
e: number;
|
|
65
|
+
} | null;
|
|
66
|
+
/**
|
|
67
|
+
* The id an edit goes by on the DHT floor (WISP 403 § Edits): a text of its own there, with the edited message's id and
|
|
68
|
+
* the edit's number beside it. The same for every send of the same edit, so its retries and its receipt match.
|
|
69
|
+
*/
|
|
70
|
+
export declare function dhtEditId(id: string, e: number): string;
|
|
71
|
+
/** A sliding window of `limit` events per `windowMs`: the sender's pace and the receiver's limit. */
|
|
72
|
+
export declare class RateWindow {
|
|
73
|
+
private readonly limit;
|
|
74
|
+
private readonly windowMs;
|
|
75
|
+
private readonly now;
|
|
76
|
+
private recent;
|
|
77
|
+
constructor(limit: number, windowMs: number, now?: () => number);
|
|
78
|
+
/** Counts one now; false (and not counted) when the window is full. */
|
|
79
|
+
take(): boolean;
|
|
80
|
+
/** Milliseconds until the window has room again; 0 when it has room now. */
|
|
81
|
+
wait(): number;
|
|
82
|
+
reset(): void;
|
|
83
|
+
}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import { type FrameChannel } from "./frames.js";
|
|
2
|
+
import { type FileInfo, type FileTransferEvents } from "./files.js";
|
|
3
|
+
/** files/2: authenticated text frames work on RTC, Iroh and HyperDHT alike.
|
|
4
|
+
* Stop-and-wait credits bound each sender to one 16 KiB chunk in flight.
|
|
5
|
+
* Final receipt follows digest verification and durable sink.close, never merely send().
|
|
6
|
+
* A live transport switch moves transfers to the new channel (`rebind`): the one frame awaiting its
|
|
7
|
+
* acknowledgement goes again there, and a receiver acknowledges a frame it already applied again. */
|
|
8
|
+
export declare class PairedFiles {
|
|
9
|
+
private channel;
|
|
10
|
+
private events;
|
|
11
|
+
private incoming;
|
|
12
|
+
private outgoing;
|
|
13
|
+
private pending;
|
|
14
|
+
private done;
|
|
15
|
+
private closed;
|
|
16
|
+
constructor(channel: FrameChannel, events: FileTransferEvents & {
|
|
17
|
+
onStored?(file: FileInfo): Promise<string | undefined>;
|
|
18
|
+
});
|
|
19
|
+
/** A file going either way on this session right now. */
|
|
20
|
+
get busy(): boolean;
|
|
21
|
+
private sendFrame;
|
|
22
|
+
private exchange;
|
|
23
|
+
send(file: FileInfo, source: AsyncIterable<Uint8Array>): Promise<void>;
|
|
24
|
+
/** The session moved to another transport: transfers carry on over `channel`, where what awaits an acknowledgement goes again. */
|
|
25
|
+
rebind(channel: FrameChannel): void;
|
|
26
|
+
handle(frame: Record<string, unknown>): Promise<void>;
|
|
27
|
+
private arm;
|
|
28
|
+
private fail;
|
|
29
|
+
closeAll(): void;
|
|
30
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import { type FrameChannel } from "./frames.js";
|
|
2
|
+
import { HttpClient, HttpHost, type HostedHttpService, type LocalFetch } from "./http.js";
|
|
3
|
+
/**
|
|
4
|
+
* Shared services over a paired session: the same HTTP frames as the older data link, carried as
|
|
5
|
+
* `ph` application frames on the authenticated channel. Binary chunks travel base64url-encoded,
|
|
6
|
+
* since paired application data is text. The frames carry no `id`, so an older app drops them.
|
|
7
|
+
*/
|
|
8
|
+
export declare class PairedHttp {
|
|
9
|
+
readonly client: HttpClient;
|
|
10
|
+
readonly host: HttpHost;
|
|
11
|
+
constructor(channel: FrameChannel, getService: (id: string) => HostedHttpService | undefined, localFetch: LocalFetch);
|
|
12
|
+
/** One `ph` frame from the peer. Anything that is not HTTP traffic is ignored. */
|
|
13
|
+
handle(frame: Record<string, unknown>): void;
|
|
14
|
+
close(): void;
|
|
15
|
+
}
|