@celljs/ta-protocol 4.12.0 → 4.13.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.
@@ -10,4 +10,5 @@ export * from './room-protocol.js';
10
10
  export * from './settings-protocol.js';
11
11
  export * from './ta-extension-host.js';
12
12
  export * from './ta-protocol.js';
13
+ export * from './team-protocol.js';
13
14
  export * from './workspace-protocol.js';
@@ -10,5 +10,6 @@ export * from './room-protocol.js';
10
10
  export * from './settings-protocol.js';
11
11
  export * from './ta-extension-host.js';
12
12
  export * from './ta-protocol.js';
13
+ export * from './team-protocol.js';
13
14
  export * from './workspace-protocol.js';
14
15
  //# sourceMappingURL=index.js.map
@@ -1,3 +1,4 @@
1
+ import type { TaPackageText } from './package-protocol.js';
1
2
  export declare const TaRelayServer: unique symbol;
2
3
  export declare const TA_RELAY_SERVICE = "TaRelayServer";
3
4
  /** A device paired with this ta serve, which reaches it through a relay (@celljs/ta-relay). */
@@ -5,15 +6,133 @@ export interface TaRelayDevice {
5
6
  id: string;
6
7
  name: string;
7
8
  createdAt: number;
9
+ /** The relay it comes through. */
10
+ relay?: string;
11
+ }
12
+ /** What goes through a relay, each feature using the relay relays.json names for it (docs/design/ta-relays.md). */
13
+ export type TaRelayFeature = 'devices' | 'share' | 'rooms' | 'sync';
14
+ export type TaRelayCapability = 'tunnel' | 'hub' | 'store' | 'pages';
15
+ export interface TaRelayLimits {
16
+ hubMembers: number;
17
+ hubValueBytes: number;
18
+ hubKeys: number;
19
+ hubStateBytes: number;
20
+ hubIdleDays: number;
21
+ storeValueBytes: number;
22
+ storeDays: number;
23
+ }
24
+ /**
25
+ * A service of relays.json: a relay of Ta (`ta-relay`, the official one among them), or a folder a cloud drive keeps the
26
+ * same on the user's computers (`folder`), which only stores, for sync alone (docs/design/ta-relays.md 4.1).
27
+ */
28
+ export interface TaRelayService {
29
+ id: string;
30
+ name?: string;
31
+ /** `ta-relay`, `folder`, or a type a package registered (TaExtensionRelays.registerType: `webdav`, `s3`…). */
32
+ type: string;
33
+ /** A relay's address. */
34
+ url?: string;
35
+ /** A folder, `~/…` when under the home directory. */
36
+ path?: string;
37
+ /** The relay that comes with Ta. */
38
+ builtin: boolean;
39
+ /** The features it can carry, when not all (a folder, a store of a package: `sync` only). */
40
+ only?: TaRelayFeature[];
41
+ /** Of a type of a package: its options but the secret ones, and where it is in a few words (a host, a bucket). */
42
+ options?: Record<string, unknown>;
43
+ where?: string;
44
+ /** Of a type of a package that is off now: listed, used by nothing till it is on again. */
45
+ unavailable?: true;
46
+ }
47
+ /** A field of the form that adds a service of a type of a package (TaRelayType.options). */
48
+ export interface TaRelayOption {
49
+ key: string;
50
+ label: TaPackageText;
51
+ placeholder?: string;
52
+ /** A password or a key: never shown again, never to a page. */
53
+ secret?: boolean;
54
+ optional?: boolean;
55
+ }
56
+ /** A type of service a package registered, as the page shows it to add one. */
57
+ export interface TaRelayTypeInfo {
58
+ type: string;
59
+ title: TaPackageText;
60
+ hint?: TaPackageText;
61
+ /** The name of an icon of `pi.ui.icons`. */
62
+ icon?: string;
63
+ options: TaRelayOption[];
64
+ }
65
+ /**
66
+ * Files sync keeps sealed (docs/design/ta-relays.md 4.1): a folder of a cloud drive, a WebDAV server, a bucket of S3.
67
+ * Paths are relative, with `/`; what is written there is sealed already, named so that it tells nothing.
68
+ */
69
+ export interface TaRelayStore {
70
+ /** The files and directories right in a directory (`` for the top), each with a tag that changes when the file does. */
71
+ list(dir: string): Promise<{
72
+ name: string;
73
+ tag: string;
74
+ dir?: boolean;
75
+ }[]>;
76
+ /** Undefined when it is not there. */
77
+ read(path: string): Promise<Uint8Array | undefined>;
78
+ /** Whole, its directories made as needed. */
79
+ write(path: string, data: Uint8Array): Promise<void>;
80
+ remove(path: string): Promise<void>;
81
+ /** Hears what is written, where it can (a folder), with the path when it knows; sync looks every while anyway. */
82
+ watch?(listener: (path?: string) => void): () => void;
83
+ }
84
+ /** A type of service a package adds (TaExtensionRelays.registerType): its form, and the store it makes of what was filled in. */
85
+ export interface TaRelayType extends Omit<TaRelayTypeInfo, 'type'> {
86
+ /** What it is the same service by: two with the same key are one (a URL and a user, a bucket and a prefix). */
87
+ key(options: Record<string, unknown>): string;
88
+ /** Where it is, in a few words for the list: a host, a bucket. */
89
+ where(options: Record<string, unknown>): string;
90
+ create(options: Record<string, unknown>): TaRelayStore;
91
+ }
92
+ /** The relays and which one each feature uses (TaRelayServer.listRelays). */
93
+ export interface TaRelays {
94
+ relays: TaRelayService[];
95
+ /** Feature → id of the relay it uses. */
96
+ use: Record<TaRelayFeature, string>;
97
+ /** relays.json in the agent directory, to edit by hand. */
98
+ file: string;
99
+ /** It does not parse: every feature uses the relay of before till it is fixed. */
100
+ error?: string;
101
+ /** Folders of cloud drives found on this computer (iCloud Drive, OneDrive, Dropbox…), to add for sync. */
102
+ drives?: {
103
+ name: string;
104
+ path: string;
105
+ }[];
106
+ /** The types of services packages registered (WebDAV, S3…), to add one of. */
107
+ types?: TaRelayTypeInfo[];
108
+ }
109
+ /** What asking a relay what it is found (TaRelayServer.probeRelay). */
110
+ export interface TaRelayProbe {
111
+ online: boolean;
112
+ capabilities?: TaRelayCapability[];
113
+ limits?: TaRelayLimits;
114
+ /** Rooms and copies stay when it restarts. */
115
+ persistent?: boolean;
116
+ /** A folder: where it is on this computer. */
117
+ path?: string;
118
+ /** It answers, but is a relay made before it said what it is. */
119
+ legacy?: boolean;
120
+ ms?: number;
121
+ error?: string;
8
122
  }
9
123
  export interface TaRelayInfo {
10
124
  /** The relay of the devices; none before the first is paired. */
11
125
  relay?: string;
12
- /** The relay a new pairing uses when the user names none. */
126
+ /** The relay a new pairing uses when the user names none: the one relays.json names for devices. */
13
127
  defaultRelay: string;
14
128
  /** ta serve is connected to the relay now: the devices can reach it. */
15
129
  online: boolean;
16
130
  devices: TaRelayDevice[];
131
+ /**
132
+ * Whether ta serve keeps this computer from sleeping while idle, as long as a session runs or a device was
133
+ * connected of late; none where it cannot (only macOS can). The display still sleeps; a closed lid still does.
134
+ */
135
+ keepAwake?: boolean;
17
136
  }
18
137
  /** Pairing devices from a client, as `ta pair` does in a terminal. */
19
138
  export interface TaRelayServer {
@@ -25,6 +144,28 @@ export interface TaRelayServer {
25
144
  }>;
26
145
  /** The device can no longer reach this ta serve, at once. */
27
146
  unpair(deviceId: string): Promise<void>;
147
+ /** TaRelayInfo.keepAwake. */
148
+ setKeepAwake(on: boolean): Promise<void>;
149
+ /** The relays of relays.json and which one each feature uses. */
150
+ listRelays(): Promise<TaRelays>;
151
+ /** Adds a relay of Ta by its address (`https://…`), after asking it what it is: its id. */
152
+ addRelay(url: string, name?: string): Promise<string>;
153
+ /** Adds a folder a cloud drive keeps the same on the user's computers (iCloud Drive, OneDrive…), for sync: its id. */
154
+ addFolder(path: string, name?: string): Promise<string>;
155
+ /**
156
+ * Adds a service of a type a package registered (TaRelayTypeInfo), filled in by the user, after trying it (a file
157
+ * written, read and removed): its id, the one of before for the same service.
158
+ */
159
+ addStore(type: string, options: Record<string, unknown>, name?: string): Promise<string>;
160
+ /** Removes a relay no feature uses; what is on it (devices, rooms, links) stays on it. */
161
+ removeRelay(id: string): Promise<void>;
162
+ /**
163
+ * The relay a feature uses from now on; `null` for the default. What it made before (devices, rooms, links) stays
164
+ * on the relay it was made on.
165
+ */
166
+ chooseRelay(feature: TaRelayFeature, id: string | null): Promise<TaRelays>;
167
+ /** Asks a relay, by its id or address, what it can do and how much; never throws. */
168
+ probeRelay(idOrUrl: string): Promise<TaRelayProbe>;
28
169
  /**
29
170
  * A link of a package of this computer (by its id of listPackages, or of one of its web extensions), for
30
171
  * another computer to open it without installing: its files go from here to there through the relay, end to
@@ -11,6 +11,11 @@ export type TaRoomStatus = 'member' | 'waiting' | 'refused' | 'gone';
11
11
  export interface TaIdentity {
12
12
  id: string;
13
13
  name: string;
14
+ /**
15
+ * The user's other computers are this Ta too (ta-sync shares the identity, or a move brought it): what answers in a
16
+ * room agrees first which computer does (docs/design/ta-sync.md 9).
17
+ */
18
+ shared?: true;
14
19
  }
15
20
  export interface TaRoomMember {
16
21
  /** Its id in this room alone: what messages say they are `from`, and `to` sends to. */
@@ -31,6 +36,13 @@ export interface TaRoomInfo {
31
36
  title: string;
32
37
  /** The view that shows it (`ui.showView`), as the extension that made it said. */
33
38
  view?: string;
39
+ /**
40
+ * Not on the Rooms page, nor a group chat or a room of doubles: a room an extension keeps for itself (the user's
41
+ * own computers, ta-sync). Who asks to join it is asked of the user by that extension, still only on the user's word.
42
+ */
43
+ unlisted?: true;
44
+ /** The relay it is on; none from a Ta of before. */
45
+ relay?: string;
34
46
  /** This Ta made it. */
35
47
  owner: boolean;
36
48
  ownerName: string;
@@ -51,19 +63,37 @@ export interface TaRoomRequest {
51
63
  /** Its identity, and the name it gives. */
52
64
  id: string;
53
65
  name: string;
54
- /** Met before, in another room. */
66
+ /** A friend of the user. */
55
67
  friend: boolean;
56
68
  /** Asks from a browser, without Ta: admitted, it only chats. */
57
69
  guest?: boolean;
58
70
  at: number;
59
71
  }
60
- /** One met in a room. */
61
- export interface TaFriend extends TaIdentity {
62
- /** Titles of rooms shared, the latest last. */
63
- rooms: string[];
72
+ /**
73
+ * A friend (docs/design/ta-link.md 3.1): one kind of friend in Ta, on the word of both. `friend` once each is in the
74
+ * other's room of friends, `adding` while the user asked and the other has not answered (or its Ta is not on yet).
75
+ */
76
+ export interface TaFriend {
77
+ id: string;
78
+ name: string;
79
+ status: 'friend' | 'adding';
80
+ online: boolean;
64
81
  metAt: number;
65
82
  seenAt: number;
66
83
  }
84
+ /** One asking the user to be friends: by the user's link (`link`), or in a room the two share (`room`, its title). */
85
+ export interface TaFriendRequest {
86
+ id: string;
87
+ name: string;
88
+ at: number;
89
+ via: 'link' | 'room';
90
+ room?: string;
91
+ }
92
+ /**
93
+ * The kind of a Ta's room of friends: unlisted, its members the friends. Features that give friends something keep it
94
+ * in this room (Moments its posts, `post:` and the like); `back:` is the rooms' own.
95
+ */
96
+ export declare const TA_FRIENDS_KIND = "ta-friends";
67
97
  export interface TaRoomValue {
68
98
  value: unknown;
69
99
  version: number;
@@ -78,6 +108,11 @@ export type TaRoomEvent =
78
108
  } | {
79
109
  type: 'request';
80
110
  request: TaRoomRequest;
111
+ }
112
+ /** One asks the user to be friends (TaRoomServer.listFriendRequests). */
113
+ | {
114
+ type: 'friend';
115
+ request: TaFriendRequest;
81
116
  } | {
82
117
  type: 'message';
83
118
  room: string;
@@ -97,10 +132,16 @@ export interface TaRoomServer {
97
132
  getIdentity(): Promise<TaIdentity>;
98
133
  setName(name: string): Promise<TaIdentity>;
99
134
  listRooms(): Promise<TaRoomInfo[]>;
135
+ /**
136
+ * `use`: the feature of relays.json whose relay the room is made on (`sync` for the user's computers); `rooms` by
137
+ * default. The room stays on that relay whatever relays.json says later.
138
+ */
100
139
  createRoom(input: {
101
140
  kind: string;
102
141
  title: string;
103
142
  view?: string;
143
+ unlisted?: boolean;
144
+ use?: string;
104
145
  }): Promise<TaRoomInfo>;
105
146
  /**
106
147
  * The link others ask to join by (the owner only): the one of before while it has a day left; else, or with `renew`,
@@ -135,8 +176,25 @@ export interface TaRoomServer {
135
176
  ok: boolean;
136
177
  version: number;
137
178
  }>;
179
+ /** The user's friends, and those being added. */
138
180
  listFriends(): Promise<TaFriend[]>;
181
+ /** The link (and code) that asks to be the user's friend; with `renew` a new one, the one before no longer working. */
182
+ friendLink(renew?: boolean): Promise<{
183
+ link: string;
184
+ expiresAt: number;
185
+ }>;
186
+ /** Asks the one of a friend link to be friends. Ask the user first. */
187
+ addFriend(link: string): Promise<void>;
188
+ /** Asks a member of a room the user is in to be friends (its member id). Ask the user first. */
189
+ offerFriend(room: string, member: string): Promise<void>;
190
+ /** Those asking the user to be friends. */
191
+ listFriendRequests(): Promise<TaFriendRequest[]>;
192
+ /** The user's answer to one asking to be friends (its identity id). Only ever on the user's word, never on an agent's. */
193
+ answerFriend(id: string, accept: boolean): Promise<void>;
194
+ /** No longer friends, on both sides; the rooms the two share stay as they are. */
139
195
  removeFriend(id: string): Promise<boolean>;
196
+ /** The user's room of friends (TA_FRIENDS_KIND), made the first time, for features that give friends something. */
197
+ friendRoom(): Promise<TaRoomInfo>;
140
198
  /**
141
199
  * This connection hears TaRoomEvent (TaClient.onRoomEvent) from now on; again after it connected again. Without
142
200
  * `messages`, only `rooms` and `request`: messages and the state come often (a game's), for a page that shows them;
@@ -160,7 +218,54 @@ export declare namespace TaRoomWatchUtil {
160
218
  function same(a: TaRoomWatch | undefined, b: TaRoomWatch | undefined): boolean;
161
219
  function hears(watch: TaRoomWatch, event: TaRoomEvent): boolean;
162
220
  }
221
+ /** A room as rooms.json keeps it, with its keys: what the user's computers hand each other (TaIdentityBundle). */
222
+ export interface TaRoomRecord {
223
+ id: string;
224
+ kind: string;
225
+ /** This Ta's id in the room: one membership, whichever computer holds it. */
226
+ member: string;
227
+ status: TaRoomStatus;
228
+ [field: string]: unknown;
229
+ }
230
+ /**
231
+ * What makes this Ta who it is in rooms: the identity with its private keys, the rooms with theirs, the friends. Only
232
+ * ever between the user's own computers, sealed, never to a page.
233
+ */
234
+ export interface TaIdentityBundle {
235
+ identity: TaIdentity & Record<string, unknown>;
236
+ rooms: TaRoomRecord[];
237
+ friends: TaFriendRecord[];
238
+ }
239
+ /** A friend as friends.json keeps it: what the user's computers hand each other. */
240
+ export interface TaFriendRecord {
241
+ id: string;
242
+ name: string;
243
+ metAt: number;
244
+ seenAt: number;
245
+ [field: string]: unknown;
246
+ }
247
+ /** What a TaIdentityBundle did here: whether this Ta took on another identity, the rooms and friends it got. */
248
+ export interface TaIdentityImport {
249
+ switched: boolean;
250
+ rooms: number;
251
+ friends: number;
252
+ }
163
253
  /** The rooms for the server side of packages (TaExtensionHost.rooms): TaRoomServer, its events heard directly. */
164
254
  export interface TaRooms extends Omit<TaRoomServer, 'watch' | 'unwatch'> {
165
255
  onEvent(listener: (event: TaRoomEvent) => void): () => void;
256
+ /** For ta-sync alone, to move or share the identity between the user's computers (TaIdentityBundle). */
257
+ exportIdentity(): Promise<TaIdentityBundle>;
258
+ /**
259
+ * Takes on the identity of the user's other computer with its rooms and friends: the rooms this Ta is in keep the
260
+ * identity they were joined with; `shared` marks the identity as used on several computers.
261
+ */
262
+ importIdentity(bundle: TaIdentityBundle, options?: {
263
+ shared?: boolean;
264
+ }): Promise<TaIdentityImport>;
265
+ setIdentityShared(shared: boolean): Promise<void>;
266
+ /** A room as the user's other computer has it, merged with this one's record of the same membership. */
267
+ upsertRoom(record: TaRoomRecord): Promise<boolean>;
268
+ /** A room the user's other computer left: forgotten here without a word to the relay. */
269
+ forgetRoom(room: string, member: string): Promise<boolean>;
270
+ mergeFriends(friends: TaIdentityBundle['friends']): Promise<number>;
166
271
  }
@@ -1,5 +1,10 @@
1
1
  export const TaRoomServer = Symbol('TaRoomServer');
2
2
  export const TA_ROOM_SERVICE = 'TaRoomServer';
3
+ /**
4
+ * The kind of a Ta's room of friends: unlisted, its members the friends. Features that give friends something keep it
5
+ * in this room (Moments its posts, `post:` and the like); `back:` is the rooms' own.
6
+ */
7
+ export const TA_FRIENDS_KIND = 'ta-friends';
3
8
  export var TaRoomWatchUtil;
4
9
  (function (TaRoomWatchUtil) {
5
10
  function of(messages, state) {