@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 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
- Browser and Electron client for Lynkoria messaging, presence and calls.
4
- Your app never holds a service key: `getMessagingToken` and `getJoinToken` call **your** product backend,
5
- which authorizes the user and asks Lynkoria (via `@lynkoria/server`) for short-lived tokens.
3
+ [![npm](https://img.shields.io/npm/v/@lynkoria/client)](https://www.npmjs.com/package/@lynkoria/client)
4
+ [![license](https://img.shields.io/npm/l/@lynkoria/client)](./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
- baseUrl: 'https://api.lynkoria.com',
12
- getMessagingToken: () => productApi.fetchLynkoriaMessagingToken(),
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
- const session = await rtc.calls.join({ getJoinToken: () => productApi.fetchJoinToken('call_789') });
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`; the client applies
35
- them in order, drops duplicates, and on a gap or any reconnect fetches `after_seq` to catch up.
36
- Retrying `send` with the same `clientMessageId` never duplicates a message.
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
- ## React Native
81
+ ## License
39
82
 
40
- The included media adapter uses browser `livekit-client`; native media is not implemented or device-verified. Messaging accepts platform fetch/ID adapters. For product-owned native calling, use a development build with `@livekit/react-native` and `@livekit/react-native-webrtc` (Expo Go is not
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
- /** e.g. https://api.lynkoria.com */
70
- baseUrl: string;
71
- /** Calls your product backend, which mints a Lynkoria messaging token with its service key. */
72
- getMessagingToken: () => Promise<TokenResult>;
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.1.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.1.0",
27
- "livekit-client": "^2.24.0",
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": {