@lynkoria/server 0.1.1 → 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 CHANGED
@@ -1,5 +1,34 @@
1
1
  # @lynkoria/server
2
2
 
3
+ ## 0.2.0
4
+
5
+ ### Minor Changes
6
+
7
+ - e96fe9d: Call controls, added for products moving from Agora:
8
+
9
+ - `calls.create({ restartIfEnded: true })` starts a new call when the call for that `productCallId` has ended, so an ID can be reused like an Agora channel name (a meeting link people come back to). Without it, an ended ID still returns `409 conflict`.
10
+ - `calls.joinToken()` accepts `ttlSeconds` (30–300, default 300) and `publishSources` (for example `['camera', 'microphone']` to forbid screen sharing; enforced by the media server).
11
+ - `calls.removeUser(callId, userId)` disconnects every device of a user and resolves with how many were connected. An unused join token stays valid until it expires, so also stop issuing tokens to that user.
12
+
13
+ Requires the Lynkoria API released on or after 2026-11-18.
14
+ - 0ee4045: SDKs no longer need an API URL.
15
+
16
+ - `@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.
17
+ - `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).
18
+ - `@lynkoria/client`: `getMessagingToken` is optional for calls-only apps; without it `connect()` does nothing and messaging methods reject with a clear error.
19
+
20
+ **Upgrade:** remove `baseUrl` from `createLynkoria` and `createLynkoriaServer` (existing values keep working), and return the full `messagingToken()` result instead of only `token`.
21
+
22
+ **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.
23
+
24
+ ### Patch Changes
25
+
26
+ - 19ae236: Retries of idempotent operations now back off when a 429 or 5xx response has no `Retry-After` header; before, they retried immediately.
27
+ - 0a7c608: After you rotate a webhook signing secret in the console, Lynkoria signs each delivery with both the new and the previous secret for 24 hours. `webhooks.verify` accepts a delivery when any signature matches, so receivers can deploy the new secret without missing events. The README and docs show raw-body verification for Express, Hono, NestJS and Next.js.
28
+ - Updated dependencies [e96fe9d]
29
+ - Updated dependencies [0ee4045]
30
+ - @lynkoria/contracts@0.2.0
31
+
3
32
  ## 0.1.1
4
33
 
5
34
  ### Patch Changes
package/README.md CHANGED
@@ -26,13 +26,17 @@ Requires Node.js 22.12 or later. ES module with TypeScript types.
26
26
  import { createLynkoriaServer } from '@lynkoria/server';
27
27
 
28
28
  const lynkoria = createLynkoriaServer({
29
- baseUrl: 'https://api.lynkoria.com',
30
29
  serviceKey: process.env.LYNKORIA_SERVICE_KEY!,
31
30
  webhookSecret: process.env.LYNKORIA_WEBHOOK_SECRET,
32
31
  });
33
32
 
34
- // 1. Create (or reuse) a call for something in your product.
35
- const call = await lynkoria.calls.create({ productCallId: 'call_789', type: 'group' });
33
+ // 1. Create (or reuse) a call for something in your product. restartIfEnded starts a new call
34
+ // when the previous one with this ID has ended (a meeting link people come back to).
35
+ const call = await lynkoria.calls.create({
36
+ productCallId: 'meeting_789',
37
+ type: 'group',
38
+ restartIfEnded: true,
39
+ });
36
40
 
37
41
  // 2. After your own authorization checks, give this user a join token.
38
42
  const { url, token } = await lynkoria.calls.joinToken({
@@ -41,38 +45,50 @@ const { url, token } = await lynkoria.calls.joinToken({
41
45
  deviceId: session.deviceId,
42
46
  displayName: session.displayName,
43
47
  role: 'participant',
48
+ ttlSeconds: 120, // optional: time to connect, 30-300 (default 300)
49
+ publishSources: ['camera', 'microphone'], // optional: e.g. no screen sharing
44
50
  });
45
51
 
46
52
  // 3. Messaging: a short-lived token for @lynkoria/client.
47
- const { token: messagingToken } = await lynkoria.sessions.messagingToken({
53
+ // Return the whole result ({ token, expiresAt, apiUrl }) to the client unchanged.
54
+ const messagingToken = await lynkoria.sessions.messagingToken({
48
55
  userId: session.userId,
49
56
  deviceId: session.deviceId,
50
57
  });
51
58
 
52
59
  // 4. Webhooks: verify the signature on the raw request body.
53
- const event = lynkoria.webhooks.verify(rawBody, req.headers['lynkoria-signature']);
60
+ const event = lynkoria.webhooks.verify(rawBody, request.headers.get('lynkoria-signature'));
54
61
  ```
55
62
 
56
- Return `url` and `token` (or `messagingToken`) to your app, which passes them to
63
+ Return the join credentials and `messagingToken` to your app, which passes them to
57
64
  [`@lynkoria/client`](https://www.npmjs.com/package/@lynkoria/client) or a native SDK.
58
65
 
59
66
  ## What it covers
60
67
 
61
- | Area | Methods | Guide |
62
- | ------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------ |
63
- | Calls | `calls.create`, `get`, `joinToken`, `end`, `removeParticipant`, `setRole`, `signal` | [Calls](https://lynkoria.com/docs/calls/) |
64
- | Messaging | `sessions.messagingToken`, `conversations.create`, `addMembers`, `removeMember` | [Messaging](https://lynkoria.com/docs/messaging/) |
65
- | Users | `users.suspend`, `unsuspend` | [Server SDK](https://lynkoria.com/docs/server-sdk/) |
66
- | Notifications | `notifications.send` | [Push](https://lynkoria.com/docs/push-notifications/) |
67
- | Recordings | `recordings.start`, `list`, `get`, `stop`, `download`, `delete` | [Recording](https://lynkoria.com/docs/recording-and-egress/) |
68
- | Webhooks | `webhooks.verify`, or the standalone `verifyWebhook` | [Webhooks](https://lynkoria.com/docs/webhooks/) |
68
+ | Area | Methods | Guide |
69
+ | ------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
70
+ | Calls | `calls.create`, `get`, `joinToken`, `end`, `removeParticipant`, `removeUser`, `setRole`, `signal` | [Calls](https://lynkoria.com/docs/calls/) |
71
+ | Messaging | `sessions.messagingToken`, `conversations.create`, `addMembers`, `removeMember` | [Messaging](https://lynkoria.com/docs/messaging/) |
72
+ | Users | `users.suspend`, `unsuspend` | [Server SDK](https://lynkoria.com/docs/server-sdk/) |
73
+ | Notifications | `notifications.send` | [Push](https://lynkoria.com/docs/push-notifications/) |
74
+ | Recordings | `recordings.start`, `list`, `get`, `stop`, `download`, `delete` | [Recording](https://lynkoria.com/docs/recording-and-egress/) |
75
+ | Webhooks | `webhooks.verify`, or the standalone `verifyWebhook` | [Webhooks](https://lynkoria.com/docs/webhooks/) |
69
76
 
70
77
  The full method list is in the [server SDK reference](https://lynkoria.com/docs/server-sdk/).
71
78
 
72
79
  ## Errors and delivery
73
80
 
74
81
  Failed calls throw `LynkoriaError` with `code`, `status` and `requestId`; see [errors](https://lynkoria.com/docs/errors/).
75
- Webhooks are delivered at least once, so deduplicate by `event.id`.
82
+ Idempotent operations retry network errors, 429, 502, 503 and 504 with backoff (`maxRetries`, default 2).
83
+ Webhooks are delivered at least once, so deduplicate by `event.id`. When you rotate the webhook secret in
84
+ the console, deliveries are signed with both the old and the new secret for 24 hours, so you can deploy
85
+ the new one without missing events.
86
+
87
+ ## Keep the service key on the server
88
+
89
+ `createLynkoriaServer` throws in a browser or React Native app, where the service key would reach every
90
+ user. Mint tokens on your backend and use [`@lynkoria/client`](https://www.npmjs.com/package/@lynkoria/client)
91
+ in the app.
76
92
 
77
93
  ## Related packages
78
94
 
package/dist/index.d.ts CHANGED
@@ -1,8 +1,10 @@
1
- import { Call, CallSignalRequest, Conversation, CreateCallRequest, CreateConversationRequest, ErrorCode, JoinTokenRequest, JoinTokenResponse, LynkoriaError, MessagingTokenRequest, MessagingTokenResponse, ParticipantRole, Recording, RecordingDownload, SendNotificationRequest, SendNotificationResponse, StartRecordingRequest, WEBHOOK_SIGNATURE_HEADER, WebhookEvent } from "@lynkoria/contracts";
1
+ import { Call, CallSignalRequest, Conversation, CreateCallRequest, CreateConversationRequest, ErrorCode, JoinTokenRequest, JoinTokenResponse, LynkoriaError, MessagingTokenRequest, MessagingTokenResponse, ParticipantRole, Recording, RecordingDownload, RemoveUserResponse, SendNotificationRequest, SendNotificationResponse, StartRecordingRequest, WEBHOOK_SIGNATURE_HEADER, WebhookEvent } from "@lynkoria/contracts";
2
2
  export type * from "@lynkoria/contracts";
3
+ /** The Lynkoria API. */
4
+ export declare const DEFAULT_API_URL = "https://api.lynkoria.com";
3
5
  export type LynkoriaServerOptions = {
4
- /** e.g. https://api.lynkoria.com */
5
- baseUrl: string;
6
+ /** Overrides the API origin ({@link DEFAULT_API_URL}); for local development and tests. */
7
+ baseUrl?: string;
6
8
  /** `lynk_live_…` / `lynk_test_…` from your secret manager. Never ship it to a client. */
7
9
  serviceKey: string;
8
10
  /** Signing secret for verifying Lynkoria webhooks (`whsec_…`). Pass several during rotation. */
@@ -25,6 +27,11 @@ export type LynkoriaServer = {
25
27
  }): Promise<JoinTokenResponse>;
26
28
  end(callId: string): Promise<Call>;
27
29
  removeParticipant(callId: string, identity: string): Promise<void>;
30
+ /**
31
+ * Disconnects every device of `userId`; resolves with how many were connected. An unused join
32
+ * token stays valid until it expires, so also stop issuing tokens to the user.
33
+ */
34
+ removeUser(callId: string, userId: string): Promise<RemoveUserResponse>;
28
35
  setRole(callId: string, identity: string, role: ParticipantRole): Promise<void>;
29
36
  signal(callId: string, input: CallSignalRequest): Promise<void>;
30
37
  };
package/dist/index.js CHANGED
@@ -1,10 +1,18 @@
1
1
  import { createHmac, timingSafeEqual } from "node:crypto";
2
2
  import { ErrorCode, ErrorCode as ErrorCode$1, LynkoriaError, LynkoriaError as LynkoriaError$1, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TOLERANCE_SECONDS } from "@lynkoria/contracts";
3
3
  // src/index.ts
4
+ /** The Lynkoria API. */
5
+ const DEFAULT_API_URL = "https://api.lynkoria.com";
4
6
  const enc = encodeURIComponent;
7
+ /** True in a browser or React Native, where a service key would ship to every user. */
8
+ function isClientRuntime() {
9
+ const g = globalThis;
10
+ return typeof g.window !== "undefined" && typeof g.document !== "undefined" || g.navigator?.product === "ReactNative";
11
+ }
5
12
  function createLynkoriaServer(opts) {
6
- if (!/^lynk_(live|test)_/.test(opts.serviceKey)) throw new Error("serviceKey must be a lynk_live_ or lynk_test_ key");
7
- const base = opts.baseUrl.replace(/\/+$/, "");
13
+ if (isClientRuntime()) throw new Error("@lynkoria/server must run on your backend: a service key in a browser or mobile app is exposed to every user. Mint tokens on the server and use @lynkoria/client in the app.");
14
+ if (!/^lynk_(live|test)_/.test(opts.serviceKey ?? "")) throw new Error("serviceKey must be a lynk_live_ or lynk_test_ key (is LYNKORIA_SERVICE_KEY set on the server?)");
15
+ const base = (opts.baseUrl || "https://api.lynkoria.com").replace(/\/+$/, "");
8
16
  const doFetch = opts.fetch ?? fetch;
9
17
  const timeoutMs = opts.timeoutMs ?? 1e4;
10
18
  const maxRetries = Math.max(0, opts.maxRetries ?? 2);
@@ -43,7 +51,8 @@ function createLynkoriaServer(opts) {
43
51
  }
44
52
  if (!res.ok) {
45
53
  const error = LynkoriaError$1.fromBody(res.status, json);
46
- const retryAfter = Number(res.headers.get("retry-after"));
54
+ const header = res.headers.get("retry-after");
55
+ const retryAfter = header === null || header.trim() === "" ? NaN : Number(header);
47
56
  if (Number.isFinite(retryAfter) && retryAfter >= 0) retryAfterSeconds.set(error, retryAfter);
48
57
  throw error;
49
58
  }
@@ -57,6 +66,7 @@ function createLynkoriaServer(opts) {
57
66
  joinToken: ({ callId, ...input }) => idempotent("POST", `/v1/calls/${enc(callId)}/join-token`, input),
58
67
  end: (callId) => idempotent("POST", `/v1/calls/${enc(callId)}/end`),
59
68
  removeParticipant: (callId, identity) => idempotent("POST", `/v1/calls/${enc(callId)}/participants/${enc(identity)}/remove`),
69
+ removeUser: (callId, userId) => idempotent("POST", `/v1/calls/${enc(callId)}/users/${enc(userId)}/remove`),
60
70
  setRole: (callId, identity, role) => idempotent("POST", `/v1/calls/${enc(callId)}/participants/${enc(identity)}/permissions`, { role }),
61
71
  signal: (callId, input) => request("POST", `/v1/calls/${enc(callId)}/signal`, input)
62
72
  },
@@ -115,4 +125,4 @@ function verifyWebhook(rawBody, header, secrets, nowSeconds = Math.floor(Date.no
115
125
  })) throw new LynkoriaError$1(ErrorCode$1.Unauthorized, "Invalid webhook signature");
116
126
  return JSON.parse(rawBody);
117
127
  }
118
- export { ErrorCode, LynkoriaError, WEBHOOK_SIGNATURE_HEADER, createLynkoriaServer, verifyWebhook };
128
+ export { DEFAULT_API_URL, ErrorCode, LynkoriaError, WEBHOOK_SIGNATURE_HEADER, createLynkoriaServer, verifyWebhook };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lynkoria/server",
3
- "version": "0.1.1",
3
+ "version": "0.2.0",
4
4
  "description": "Lynkoria server SDK for product backends: calls, tokens, conversations, webhook verification",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",
@@ -26,7 +26,7 @@
26
26
  "access": "public"
27
27
  },
28
28
  "dependencies": {
29
- "@lynkoria/contracts": "^0.1.1"
29
+ "@lynkoria/contracts": "^0.2.0"
30
30
  },
31
31
  "devDependencies": {
32
32
  "@lynkoria/config": "0.0.0",