@lynkoria/server 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,38 @@
1
+ # @lynkoria/server
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
+
32
+ ## 0.1.1
33
+
34
+ ### Patch Changes
35
+
36
+ - 349320f: READMEs now cover install, requirements and a quick start, list the main API, and link to the documentation at lynkoria.com/docs.
37
+ - Updated dependencies [349320f]
38
+ - @lynkoria/contracts@0.1.1
package/README.md CHANGED
@@ -1,37 +1,101 @@
1
1
  # @lynkoria/server
2
2
 
3
- Server SDK for Guildsman product backends (VibeLynk, Fidescript, LumoLynk). Your backend authorizes the
4
- user first, then asks Lynkoria for short-lived tokens with its **service key**. Never ship the service key
5
- to a browser or mobile app.
3
+ [![npm](https://img.shields.io/npm/v/@lynkoria/server)](https://www.npmjs.com/package/@lynkoria/server)
4
+ [![license](https://img.shields.io/npm/l/@lynkoria/server)](./LICENSE)
5
+
6
+ Server SDK for your **product backend**. Your backend authorizes the user, then asks Lynkoria for short-lived
7
+ tokens with its **service key**: join tokens for calls and livestreams, and messaging tokens for chat and
8
+ presence. It also creates calls and conversations, moderates users and verifies webhooks.
9
+
10
+ > Keep the service key on the server. Never ship it to a browser or mobile app.
11
+
12
+ **[Documentation](https://lynkoria.com/docs/)** · [Server SDK guide](https://lynkoria.com/docs/server-sdk/) ·
13
+ [Quickstart](https://lynkoria.com/docs/quickstart/) · [Webhooks](https://lynkoria.com/docs/webhooks/)
14
+
15
+ ## Install
16
+
17
+ ```bash
18
+ npm install @lynkoria/server
19
+ ```
20
+
21
+ Requires Node.js 22.12 or later. ES module with TypeScript types.
22
+
23
+ ## Quick start
6
24
 
7
25
  ```ts
8
26
  import { createLynkoriaServer } from '@lynkoria/server';
9
27
 
10
28
  const lynkoria = createLynkoriaServer({
11
- baseUrl: 'https://api.lynkoria.com',
12
29
  serviceKey: process.env.LYNKORIA_SERVICE_KEY!,
13
30
  webhookSecret: process.env.LYNKORIA_WEBHOOK_SECRET,
14
31
  });
15
32
 
16
- const call = await lynkoria.calls.create({ productCallId: 'call_789', type: 'group' });
17
- // After your own authorization checks for this user and call:
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
+ });
40
+
41
+ // 2. After your own authorization checks, give this user a join token.
18
42
  const { url, token } = await lynkoria.calls.joinToken({
19
43
  callId: call.id,
20
44
  userId: session.userId,
21
45
  deviceId: session.deviceId,
22
46
  displayName: session.displayName,
23
47
  role: 'participant',
48
+ ttlSeconds: 120, // optional: time to connect, 30-300 (default 300)
49
+ publishSources: ['camera', 'microphone'], // optional: e.g. no screen sharing
24
50
  });
25
51
 
26
- const { token: messagingToken } = await lynkoria.sessions.messagingToken({
27
- userId,
28
- deviceId,
29
- tenantId,
52
+ // 3. Messaging: a short-lived token for @lynkoria/client.
53
+ // Return the whole result ({ token, expiresAt, apiUrl }) to the client unchanged.
54
+ const messagingToken = await lynkoria.sessions.messagingToken({
55
+ userId: session.userId,
56
+ deviceId: session.deviceId,
30
57
  });
31
58
 
32
- // Verify webhooks on the raw body:
33
- const event = lynkoria.webhooks.verify(rawBody, req.headers['lynkoria-signature']);
59
+ // 4. Webhooks: verify the signature on the raw request body.
60
+ const event = lynkoria.webhooks.verify(rawBody, request.headers.get('lynkoria-signature'));
34
61
  ```
35
62
 
36
- Errors are thrown as `LynkoriaError` with `code`, `status` and `requestId`. Webhook delivery is
37
- at-least-once: dedupe by `event.id`.
63
+ Return the join credentials and `messagingToken` to your app, which passes them to
64
+ [`@lynkoria/client`](https://www.npmjs.com/package/@lynkoria/client) or a native SDK.
65
+
66
+ ## What it covers
67
+
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/) |
76
+
77
+ The full method list is in the [server SDK reference](https://lynkoria.com/docs/server-sdk/).
78
+
79
+ ## Errors and delivery
80
+
81
+ Failed calls throw `LynkoriaError` with `code`, `status` and `requestId`; see [errors](https://lynkoria.com/docs/errors/).
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.
92
+
93
+ ## Related packages
94
+
95
+ - [`@lynkoria/client`](https://www.npmjs.com/package/@lynkoria/client): browser and Electron client.
96
+ - [`@lynkoria/react`](https://www.npmjs.com/package/@lynkoria/react): React hooks.
97
+ - [`@lynkoria/contracts`](https://www.npmjs.com/package/@lynkoria/contracts): shared schemas, events and error codes.
98
+
99
+ ## License
100
+
101
+ [Apache-2.0](./LICENSE)
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.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.1.0"
29
+ "@lynkoria/contracts": "^0.2.0"
30
30
  },
31
31
  "devDependencies": {
32
32
  "@lynkoria/config": "0.0.0",