@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 +29 -0
- package/README.md +31 -15
- package/dist/index.d.ts +10 -3
- package/dist/index.js +14 -4
- package/package.json +2 -2
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
|
-
|
|
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
|
-
|
|
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,
|
|
60
|
+
const event = lynkoria.webhooks.verify(rawBody, request.headers.get('lynkoria-signature'));
|
|
54
61
|
```
|
|
55
62
|
|
|
56
|
-
Return
|
|
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
|
|
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`
|
|
65
|
-
| Users | `users.suspend`, `unsuspend`
|
|
66
|
-
| Notifications | `notifications.send`
|
|
67
|
-
| Recordings | `recordings.start`, `list`, `get`, `stop`, `download`, `delete`
|
|
68
|
-
| Webhooks | `webhooks.verify`, or the standalone `verifyWebhook`
|
|
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
|
-
|
|
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
|
-
/**
|
|
5
|
-
baseUrl
|
|
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 (
|
|
7
|
-
|
|
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
|
|
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.
|
|
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.
|
|
29
|
+
"@lynkoria/contracts": "^0.2.0"
|
|
30
30
|
},
|
|
31
31
|
"devDependencies": {
|
|
32
32
|
"@lynkoria/config": "0.0.0",
|