@lynkoria/client 0.1.0 → 0.2.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.
- package/CHANGELOG.md +29 -0
- package/README.md +57 -15
- package/dist/index.d.ts +12 -4
- package/dist/index.js +39 -6
- package/package.json +3 -3
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# @lynkoria/client
|
|
2
|
+
|
|
3
|
+
## 0.2.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 0ee4045: SDKs no longer need an API URL.
|
|
8
|
+
|
|
9
|
+
- `@lynkoria/server`: `baseUrl` is optional and defaults to `https://api.lynkoria.com` (exported as `DEFAULT_API_URL`); `createLynkoriaServer({ serviceKey })` is enough. It now throws in a browser or React Native app, where the service key would reach every user.
|
|
10
|
+
- `sessions.messagingToken()` returns `apiUrl` next to the token. Return the whole result from your token endpoint to the client: `@lynkoria/client` then needs no `baseUrl`, and only accepts an `https:` `apiUrl` (plain `http:` for localhost).
|
|
11
|
+
- `@lynkoria/client`: `getMessagingToken` is optional for calls-only apps; without it `connect()` does nothing and messaging methods reject with a clear error.
|
|
12
|
+
|
|
13
|
+
**Upgrade:** remove `baseUrl` from `createLynkoria` and `createLynkoriaServer` (existing values keep working), and return the full `messagingToken()` result instead of only `token`.
|
|
14
|
+
|
|
15
|
+
**Breaking for type users:** `MessagingTokenResponse` in `@lynkoria/contracts` has a required `apiUrl`. Code that constructs that type by hand (test mocks, fakes) must add it.
|
|
16
|
+
|
|
17
|
+
### Patch Changes
|
|
18
|
+
|
|
19
|
+
- Updated dependencies [e96fe9d]
|
|
20
|
+
- Updated dependencies [0ee4045]
|
|
21
|
+
- @lynkoria/contracts@0.2.0
|
|
22
|
+
|
|
23
|
+
## 0.1.1
|
|
24
|
+
|
|
25
|
+
### Patch Changes
|
|
26
|
+
|
|
27
|
+
- 349320f: READMEs now cover install, requirements and a quick start, list the main API, and link to the documentation at lynkoria.com/docs.
|
|
28
|
+
- Updated dependencies [349320f]
|
|
29
|
+
- @lynkoria/contracts@0.1.1
|
package/README.md
CHANGED
|
@@ -1,41 +1,83 @@
|
|
|
1
1
|
# @lynkoria/client
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@lynkoria/client)
|
|
4
|
+
[](./LICENSE)
|
|
5
|
+
|
|
6
|
+
Client SDK for **browsers and Electron**: realtime messaging, presence, typing, attachments and calls.
|
|
7
|
+
Your app never holds a service key. It gets short-lived tokens from **your** backend, which authorizes the
|
|
8
|
+
user and asks Lynkoria for them with [`@lynkoria/server`](https://www.npmjs.com/package/@lynkoria/server).
|
|
9
|
+
|
|
10
|
+
**[Documentation](https://lynkoria.com/docs/)** · [Client SDK guide](https://lynkoria.com/docs/client-sdk/) ·
|
|
11
|
+
[Quickstart](https://lynkoria.com/docs/quickstart/) · [Messaging](https://lynkoria.com/docs/messaging/) ·
|
|
12
|
+
[Calls](https://lynkoria.com/docs/calls/)
|
|
13
|
+
|
|
14
|
+
## Install
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npm install @lynkoria/client
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
ES module with TypeScript types. `livekit-client` is only loaded when a user joins a call, so messaging-only
|
|
21
|
+
apps do not download the media engine.
|
|
22
|
+
|
|
23
|
+
## Quick start
|
|
6
24
|
|
|
7
25
|
```ts
|
|
8
26
|
import { createLynkoria } from '@lynkoria/client';
|
|
9
27
|
|
|
10
28
|
const rtc = createLynkoria({
|
|
11
|
-
|
|
12
|
-
getMessagingToken: () =>
|
|
29
|
+
// Return your backend's whole messagingToken() result; it carries the API URL.
|
|
30
|
+
getMessagingToken: () => myBackend.fetchLynkoriaMessagingToken(),
|
|
13
31
|
});
|
|
14
32
|
|
|
15
33
|
rtc.connect();
|
|
16
|
-
const history = await rtc.messages.history('conv_123'); // also starts seq tracking
|
|
17
|
-
const off = rtc.onMessage((event) => render(event)); // ordered, deduplicated, gap-resynced
|
|
18
34
|
|
|
35
|
+
// Messaging: history, live events and sending.
|
|
36
|
+
const history = await rtc.messages.history('conv_123');
|
|
37
|
+
const off = rtc.onMessage((event) => render(event)); // ordered, deduplicated, resynced after gaps
|
|
19
38
|
await rtc.messages.send({
|
|
20
39
|
conversationId: 'conv_123',
|
|
21
|
-
clientMessageId: rtc.ids.create(),
|
|
40
|
+
clientMessageId: rtc.ids.create(), // retry with the same ID: never duplicates
|
|
22
41
|
text: 'Hello',
|
|
23
42
|
});
|
|
24
43
|
|
|
44
|
+
// Presence.
|
|
25
45
|
const unsubscribe = rtc.presence.subscribe('user_456', (p) => render(p.status));
|
|
26
46
|
|
|
27
|
-
|
|
47
|
+
// Calls: your backend returns a join token from @lynkoria/server.
|
|
48
|
+
const session = await rtc.calls.join({ getJoinToken: () => myBackend.fetchJoinToken('call_789') });
|
|
28
49
|
await session.setMicrophoneEnabled(false);
|
|
29
50
|
await session.startScreenShare();
|
|
30
51
|
```
|
|
31
52
|
|
|
53
|
+
Calls-only apps need no messaging token: `createLynkoria()` with no options can join calls, and
|
|
54
|
+
`connect()` does nothing until you add `getMessagingToken`.
|
|
55
|
+
|
|
56
|
+
## What it covers
|
|
57
|
+
|
|
58
|
+
| Area | API | Guide |
|
|
59
|
+
| ------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
|
|
60
|
+
| Connection | `connect`, `disconnect`, `onConnectionState`, `onError` | [Client SDK](https://lynkoria.com/docs/client-sdk/) |
|
|
61
|
+
| Messages | `messages.history`, `send`, `edit`, `delete`, `react`, `markRead`, `onMessage`, `onRead` | [Messaging](https://lynkoria.com/docs/messaging/) |
|
|
62
|
+
| Conversations | `conversations.list`, `track`, `untrack`, `resync`, `onConversationUpdated` | [Messaging](https://lynkoria.com/docs/messaging/) |
|
|
63
|
+
| Presence | `presence.subscribe`, `get`, `setStatus`, `typing.start`, `stop`, `onTyping` | [Presence](https://lynkoria.com/docs/presence/) |
|
|
64
|
+
| Attachments | `attachments.upload`, `downloadUrl` | [File security](https://lynkoria.com/docs/file-security-and-scanning/) |
|
|
65
|
+
| Calls | `calls.join`, mute, camera, screen share, devices, participants | [Calls](https://lynkoria.com/docs/calls/) |
|
|
66
|
+
|
|
32
67
|
## Delivery guarantees
|
|
33
68
|
|
|
34
|
-
PostgreSQL is the source of truth. Realtime events carry a per-conversation `seq
|
|
35
|
-
|
|
36
|
-
|
|
69
|
+
PostgreSQL is the source of truth. Realtime events carry a per-conversation `seq`: the client applies them
|
|
70
|
+
in order, drops duplicates, and after a gap or a reconnect fetches the missed events. Retrying `send` with
|
|
71
|
+
the same `clientMessageId` never creates a duplicate.
|
|
72
|
+
|
|
73
|
+
## Frameworks
|
|
74
|
+
|
|
75
|
+
- React: [`@lynkoria/react`](https://www.npmjs.com/package/@lynkoria/react) hooks.
|
|
76
|
+
- Next.js and TanStack Start: [Next.js guide](https://lynkoria.com/docs/nextjs/), [TanStack guide](https://lynkoria.com/docs/tanstack/).
|
|
77
|
+
- React Native: messaging works with platform `fetch` and an ID generator
|
|
78
|
+
(`ids: { create: () => yourUuid() }` when `crypto.randomUUID` is missing). For native calls, use
|
|
79
|
+
[`@lynkoria/react-native`](https://www.npmjs.com/package/@lynkoria/react-native).
|
|
37
80
|
|
|
38
|
-
##
|
|
81
|
+
## License
|
|
39
82
|
|
|
40
|
-
|
|
41
|
-
supported). If `crypto.randomUUID` is missing, pass `ids: { create: () => yourUuid() }`.
|
|
83
|
+
[Apache-2.0](./LICENSE)
|
package/dist/index.d.ts
CHANGED
|
@@ -44,9 +44,11 @@ type CallSession = {
|
|
|
44
44
|
switchDevice(kind: CallDeviceKind, deviceId: string): Promise<void>;
|
|
45
45
|
leave(): Promise<void>;
|
|
46
46
|
};
|
|
47
|
+
/** What `getMessagingToken` resolves to: the token, or your backend's whole `messagingToken()` result. */
|
|
47
48
|
type TokenResult = string | {
|
|
48
49
|
token: string;
|
|
49
50
|
expiresAt?: string;
|
|
51
|
+
apiUrl?: string;
|
|
50
52
|
};
|
|
51
53
|
/** Reads `exp` from a JWT without verifying it (verification happens on the server). */
|
|
52
54
|
export declare function jwtExpiry(token: string): number | null;
|
|
@@ -65,11 +67,17 @@ export declare class SequenceTracker {
|
|
|
65
67
|
decide(conversationId: string, seq: number): SequenceDecision;
|
|
66
68
|
}
|
|
67
69
|
export type ConnectionState = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'disconnected';
|
|
70
|
+
/** The Lynkoria API, used until a messaging token reports its `apiUrl`. */
|
|
71
|
+
export declare const DEFAULT_API_URL = "https://api.lynkoria.com";
|
|
68
72
|
export type LynkoriaClientOptions = {
|
|
69
|
-
/**
|
|
70
|
-
baseUrl
|
|
71
|
-
/**
|
|
72
|
-
|
|
73
|
+
/** Overrides the API origin from the token response; for local development and tests. */
|
|
74
|
+
baseUrl?: string;
|
|
75
|
+
/**
|
|
76
|
+
* Calls your product backend, which mints a Lynkoria messaging token with its service key.
|
|
77
|
+
* Return the whole `messagingToken()` result so the client also learns `apiUrl`. Required for
|
|
78
|
+
* messaging, presence, attachments and push; calls-only apps can omit it.
|
|
79
|
+
*/
|
|
80
|
+
getMessagingToken?: () => Promise<TokenResult>;
|
|
73
81
|
/** Injectable platform adapters (React Native: no `window`, maybe no `crypto.randomUUID`). */
|
|
74
82
|
ids?: {
|
|
75
83
|
create(): string;
|
package/dist/index.js
CHANGED
|
@@ -140,11 +140,29 @@ function jwtExpiry(token) {
|
|
|
140
140
|
return null;
|
|
141
141
|
}
|
|
142
142
|
}
|
|
143
|
+
/** The token is sent to this origin, so only accept https (plain http for local development). */
|
|
144
|
+
function checkedApiUrl(value) {
|
|
145
|
+
let url;
|
|
146
|
+
try {
|
|
147
|
+
url = new URL(value);
|
|
148
|
+
} catch {
|
|
149
|
+
throw new Error(`Invalid apiUrl from the messaging token response: ${value}`);
|
|
150
|
+
}
|
|
151
|
+
const local = [
|
|
152
|
+
"localhost",
|
|
153
|
+
"127.0.0.1",
|
|
154
|
+
"[::1]"
|
|
155
|
+
].includes(url.hostname);
|
|
156
|
+
if (url.protocol !== "https:" && !(url.protocol === "http:" && local)) throw new Error(`apiUrl must use https: ${value}`);
|
|
157
|
+
return value;
|
|
158
|
+
}
|
|
143
159
|
/** Caches the messaging token from the product backend; refreshes it within 60 s of expiry. */
|
|
144
160
|
var TokenSource = class {
|
|
145
161
|
fetchToken;
|
|
146
162
|
cached = null;
|
|
147
163
|
inflight = null;
|
|
164
|
+
/** API origin reported with the most recent token, if the backend passed it through. */
|
|
165
|
+
apiUrl = null;
|
|
148
166
|
constructor(fetchToken) {
|
|
149
167
|
this.fetchToken = fetchToken;
|
|
150
168
|
}
|
|
@@ -160,6 +178,7 @@ var TokenSource = class {
|
|
|
160
178
|
try {
|
|
161
179
|
const res = await this.fetchToken();
|
|
162
180
|
const token = typeof res === "string" ? res : res.token;
|
|
181
|
+
if (typeof res === "object" && res.apiUrl) this.apiUrl = checkedApiUrl(res.apiUrl);
|
|
163
182
|
const explicitExpiry = typeof res === "object" && res.expiresAt ? Date.parse(res.expiresAt) : NaN;
|
|
164
183
|
const expiresAt = Number.isFinite(explicitExpiry) ? explicitExpiry : jwtExpiry(token) ?? Date.now() + 3e5;
|
|
165
184
|
this.cached = {
|
|
@@ -175,6 +194,8 @@ var TokenSource = class {
|
|
|
175
194
|
}
|
|
176
195
|
};
|
|
177
196
|
// src/index.ts
|
|
197
|
+
/** The Lynkoria API, used until a messaging token reports its `apiUrl`. */
|
|
198
|
+
const DEFAULT_API_URL = "https://api.lynkoria.com";
|
|
178
199
|
function defaultIds() {
|
|
179
200
|
return { create: () => {
|
|
180
201
|
const c = globalThis.crypto;
|
|
@@ -188,10 +209,11 @@ function defaultIds() {
|
|
|
188
209
|
const conv = (id) => `/v1/conversations/${encodeURIComponent(id)}`;
|
|
189
210
|
const jitter = (ms) => ms * (.8 + Math.random() * .4);
|
|
190
211
|
function createLynkoria(opts) {
|
|
191
|
-
const base = opts.baseUrl.replace(/\/+$/, "");
|
|
192
212
|
const doFetch = opts.fetch ?? ((...args) => fetch(...args));
|
|
193
213
|
const ids = opts.ids ?? defaultIds();
|
|
194
|
-
const tokens = new TokenSource(opts.getMessagingToken);
|
|
214
|
+
const tokens = new TokenSource(opts.getMessagingToken ?? (() => Promise.reject(new LynkoriaError$1(ErrorCode$1.BadRequest, "createLynkoria: pass getMessagingToken to use messaging, presence, attachments or push"))));
|
|
215
|
+
/** Resolved after the first token, so clients need no endpoint configuration. */
|
|
216
|
+
const base = () => (opts.baseUrl ?? tokens.apiUrl ?? "https://api.lynkoria.com").replace(/\/+$/, "");
|
|
195
217
|
const tracker = new SequenceTracker();
|
|
196
218
|
const media = new LiveKitMediaProvider();
|
|
197
219
|
const connectionState = new Emitter();
|
|
@@ -220,7 +242,7 @@ function createLynkoria(opts) {
|
|
|
220
242
|
const token = await tokens.token();
|
|
221
243
|
let res;
|
|
222
244
|
try {
|
|
223
|
-
res = await doFetch(`${base}${path}`, {
|
|
245
|
+
res = await doFetch(`${base()}${path}`, {
|
|
224
246
|
method,
|
|
225
247
|
headers: {
|
|
226
248
|
authorization: `Bearer ${token}`,
|
|
@@ -297,7 +319,7 @@ function createLynkoria(opts) {
|
|
|
297
319
|
}
|
|
298
320
|
function ensureSocket() {
|
|
299
321
|
if (socket) return socket;
|
|
300
|
-
const s = io(base, {
|
|
322
|
+
const s = io(base(), {
|
|
301
323
|
path: opts.socketPath ?? "/socket.io/",
|
|
302
324
|
transports: ["websocket"],
|
|
303
325
|
autoConnect: false,
|
|
@@ -380,10 +402,21 @@ function createLynkoria(opts) {
|
|
|
380
402
|
return s;
|
|
381
403
|
}
|
|
382
404
|
function connect() {
|
|
405
|
+
if (!opts.getMessagingToken) return;
|
|
383
406
|
wantConnected = true;
|
|
407
|
+
if (!socket && !opts.baseUrl && !tokens.apiUrl) {
|
|
408
|
+
if (state === "idle") setState("connecting");
|
|
409
|
+
tokens.token().catch(() => void 0).finally(() => {
|
|
410
|
+
if (wantConnected) openSocket();
|
|
411
|
+
});
|
|
412
|
+
return;
|
|
413
|
+
}
|
|
414
|
+
openSocket();
|
|
415
|
+
}
|
|
416
|
+
function openSocket() {
|
|
384
417
|
const s = ensureSocket();
|
|
385
418
|
if (!s.connected && !s.active) {
|
|
386
|
-
setState(state === "idle" ? "connecting" : "reconnecting");
|
|
419
|
+
setState(state === "idle" || state === "connecting" ? "connecting" : "reconnecting");
|
|
387
420
|
s.connect();
|
|
388
421
|
}
|
|
389
422
|
}
|
|
@@ -543,4 +576,4 @@ function createLynkoria(opts) {
|
|
|
543
576
|
}
|
|
544
577
|
};
|
|
545
578
|
}
|
|
546
|
-
export { ErrorCode, LynkoriaError, SequenceTracker, createLynkoria, jwtExpiry };
|
|
579
|
+
export { DEFAULT_API_URL, ErrorCode, LynkoriaError, SequenceTracker, createLynkoria, jwtExpiry };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@lynkoria/client",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Lynkoria communications client SDK (browser, Electron, React Native)",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"type": "module",
|
|
@@ -23,8 +23,8 @@
|
|
|
23
23
|
"access": "public"
|
|
24
24
|
},
|
|
25
25
|
"dependencies": {
|
|
26
|
-
"@lynkoria/contracts": "^0.
|
|
27
|
-
"livekit-client": "^2.24.
|
|
26
|
+
"@lynkoria/contracts": "^0.2.0",
|
|
27
|
+
"livekit-client": "^2.24.1",
|
|
28
28
|
"socket.io-client": "^4.8.4"
|
|
29
29
|
},
|
|
30
30
|
"devDependencies": {
|