@juki-team/commons 0.1.41 → 0.1.43

package/dist/cjs/index.cjs

@@ -582,6 +582,10 @@ exports.WebSocketMessageEvent = void 0;
     WebSocketMessageEvent["CLIENT_TRACK_DEVICE"] = "CLIENT_TRACK_DEVICE";
     WebSocketMessageEvent["CHAT_COMPLETIONS"] = "CHAT_COMPLETIONS";
 })(exports.WebSocketMessageEvent || (exports.WebSocketMessageEvent = {}));
+/**
+ * Subscriptions of the client. With the TOPIC channels they are not sent to the server anymore:
+ * they only say which channel the client attaches (`getChannelOfWebSocketSubscribeEvent`) and the dispatch key.
+ */
 exports.WebSocketSubscriptionEvent = void 0;
 (function (WebSocketSubscriptionEvent) {
     WebSocketSubscriptionEvent["SUBSCRIBE_CODE_RUN_STATUS"] = "SUBSCRIBE_CODE_RUN_STATUS";
@@ -600,6 +604,9 @@ exports.WebSocketSubscriptionEvent = void 0;
     WebSocketSubscriptionEvent["UNSUBSCRIBE_CLIENT_TRACK"] = "UNSUBSCRIBE_CLIENT_TRACK";
     WebSocketSubscriptionEvent["SUBSCRIBE_USER_NOTIFICATION"] = "SUBSCRIBE_USER_NOTIFICATION";
     WebSocketSubscriptionEvent["UNSUBSCRIBE_USER_NOTIFICATION"] = "UNSUBSCRIBE_USER_NOTIFICATION";
+    // an administrator watching the data (screenshots, location, device) sent by another client
+    WebSocketSubscriptionEvent["SUBSCRIBE_CLIENT_TRACK_DATA"] = "SUBSCRIBE_CLIENT_TRACK_DATA";
+    WebSocketSubscriptionEvent["UNSUBSCRIBE_CLIENT_TRACK_DATA"] = "UNSUBSCRIBE_CLIENT_TRACK_DATA";
 })(exports.WebSocketSubscriptionEvent || (exports.WebSocketSubscriptionEvent = {}));
 exports.WebSocketResponseEvent = void 0;
 (function (WebSocketResponseEvent) {
@@ -623,6 +630,20 @@ exports.WebSocketResponseEvent = void 0;
     WebSocketResponseEvent["USER_NOTIFICATION_SUBMISSION"] = "USER_NOTIFICATION_SUBMISSION";
     WebSocketResponseEvent["USER_NOTIFICATION_CONTEST_CLARIFICATION"] = "USER_NOTIFICATION_CONTEST_CLARIFICATION";
 })(exports.WebSocketResponseEvent || (exports.WebSocketResponseEvent = {}));
+/**
+ * Roles of a contest, with the same names as the contest members in the DB.
+ * Each role has its own Ably channel: `contest:{contestKey}:{role}` (see `CHANNEL_CONTEST`).
+ * The inclusions follow `getContestAccessPermissions`:
+ *   spectators ⊇ managers ⊇ administrators, spectators ⊇ participants, spectators ⊇ guests
+ */
+exports.ContestChannelRole = void 0;
+(function (ContestChannelRole) {
+    ContestChannelRole["ADMINISTRATORS"] = "administrators";
+    ContestChannelRole["MANAGERS"] = "managers";
+    ContestChannelRole["PARTICIPANTS"] = "participants";
+    ContestChannelRole["GUESTS"] = "guests";
+    ContestChannelRole["SPECTATORS"] = "spectators";
+})(exports.ContestChannelRole || (exports.ContestChannelRole = {}));
 
 exports.DataViewMode = void 0;
 (function (DataViewMode) {
@@ -2223,11 +2244,56 @@ const EMPTY_USER_PERMISSIONS = {
     },
 };
 
+// LEGACY channels (fan-out per client through the subscriptions registry in Redis)
+/** @deprecated the subscriptions registry was replaced by the TOPIC channels granted in the Ably token */
 const CHANNEL_PUBLISH_SUBSCRIPTIONS = 'pub:subscriptions';
+/** @deprecated not used, the events arrive by the TOPIC channels */
 const CHANNEL_SUBSCRIBE_NOTIFICATIONS = 'sub:notifications';
+/** @deprecated the events arrive by the TOPIC channels */
 const CHANNEL_SUBSCRIBE_CLIENT = (clientId) => `sub:client:${clientId}`;
+/** messages from the clients to the backend (chat completions, client track screenshots) */
 const CHANNEL_PUBLISH_MESSAGES = 'pub:messages';
+/** @deprecated global presence channel (limited to 200 members by Ably), replaced by CHANNEL_COMPANY_PRESENCE */
 const CHANNEL_PRESENCE_CLIENT = 'pre:client';
+// TOPIC channels
+// The backend publishes each event once on the channel of its topic and Ably does the fan-out.
+// Who can subscribe to each channel is decided by the API in the Ably token (capability), never by the client.
+// Dynamic segments are encoded so a key can never inject a `:` (the Ably segment separator used by the wildcards).
+const segment = (value) => encodeURIComponent(value);
+/** private: events of one session (code runs, requested data, client track commands) */
+const CHANNEL_SESSION = (sessionId) => `session:${segment(sessionId)}`;
+/** private: events of one user (own submissions while the contest is frozen, notifications) */
+const CHANNEL_USER = (userId) => `user:${segment(userId)}`;
+/** public: status of a submission when it is visible to everyone */
+const CHANNEL_SUBMISSION = (submitId) => `submission:${segment(submitId)}`;
+/** public: changes of a problem */
+const CHANNEL_PROBLEM = (problemKey) => `problem:${segment(problemKey)}`;
+/** per role: events of a contest for one role (and the roles above it, see `ContestChannelRole`) */
+const CHANNEL_CONTEST = (contestKey, role) => `contest:${segment(contestKey)}:${role}`;
+/** system administrators only: data sent by a tracked client (screenshots, location, device) */
+const CHANNEL_CLIENT_TRACK = (trackedClientId) => `client-track:${segment(trackedClientId)}`;
+/**
+ * presence of the clients (tabs) of the logged users of a company (by its key), data: `UserPresenceData`.
+ * The clients only enter (capability `presence`), only the administrators of the company receive it
+ * (capability `presence-subscribe`). Ably limits the presence members per channel (200 by default,
+ * more with server-side batching enabled on the `presence` namespace).
+ * The identity of a member is its `clientId` (`sessionId|uiId`, verified by Ably), never its data.
+ */
+const CHANNEL_COMPANY_PRESENCE = (companyKey) => `presence:company:${segment(companyKey)}`;
+// capability resources (wildcards) of the public channels
+const CHANNEL_SUBMISSION_ALL = 'submission:*';
+const CHANNEL_PROBLEM_ALL = 'problem:*';
+const CHANNEL_CLIENT_TRACK_ALL = 'client-track:*';
+/**
+ * Returns the contest and role of a `CHANNEL_CONTEST` channel name, or null if it is not one.
+ */
+const getContestChannelParams = (channel) => {
+    const [namespace, contestKey, role, ...rest] = channel.split(':');
+    if (namespace !== 'contest' || !contestKey || rest.length || !Object.values(exports.ContestChannelRole).includes(role)) {
+        return null;
+    }
+    return { contestKey: decodeURIComponent(contestKey), role: role };
+};
 
 const NEW_PAGE_SHEET = () => ({
     id: uuid.v4(),
@@ -3010,6 +3076,16 @@ const isUnsubscribeUserNotificationWebSocketEventDTO = (event) => {
     return isWebsocketSubscription(event)
         && event?.event === exports.WebSocketSubscriptionEvent.UNSUBSCRIBE_USER_NOTIFICATION;
 };
+const isSubscribeClientTrackDataWebSocketEventDTO = (event) => {
+    return isWebsocketSubscription(event)
+        && event?.event === exports.WebSocketSubscriptionEvent.SUBSCRIBE_CLIENT_TRACK_DATA
+        && typeof event?.trackedClientId === 'string' && !!event.trackedClientId;
+};
+const isUnsubscribeClientTrackDataWebSocketEventDTO = (event) => {
+    return isWebsocketSubscription(event)
+        && event?.event === exports.WebSocketSubscriptionEvent.UNSUBSCRIBE_CLIENT_TRACK_DATA
+        && typeof event?.trackedClientId === 'string' && !!event.trackedClientId;
+};
 // is WebSocketResponseEventDTO, CHANNEL_SUBSCRIBE_CLIENT
 const isWebSocketResponseEventDTO = (event) => {
     return Object.values(exports.WebSocketResponseEvent).includes(event?.event)
@@ -3123,6 +3199,73 @@ const isUserNotificationContestClarificationWebSocketResponseEventDTO = (event)
 const getWebSocketResponseEventKey = (event, clientId, id) => {
     return `${event}-${clientId}-${id}`;
 };
+const isWebSocketChannelsMessageDTO = (message) => {
+    return Array.isArray(message?.channels)
+        && message.channels.every((channel) => typeof channel === 'string' && !!channel)
+        && Object.values(exports.WebSocketResponseEvent).includes(message?.event?.event);
+};
+/**
+ * Key used by the client to dispatch a response received on a TOPIC channel to its subscribers.
+ * It is the same key that `getKeyWebSocketEventDTO` (base-ui) computes for the subscription.
+ * Returns null when the response is not addressed to this client.
+ */
+const getWebSocketResponseEventKeyOfResponse = (response, clientId) => {
+    if (isCodeRunStatusMessageWebSocketResponseEventDTO(response)) {
+        return getWebSocketResponseEventKey(exports.WebSocketResponseEvent.CODE_RUN_STATUS, clientId, response.runId);
+    }
+    if (isSubmissionRunStatusMessageWebSocketResponseEventDTO(response)) {
+        return getWebSocketResponseEventKey(exports.WebSocketResponseEvent.SUBMISSION_RUN_STATUS, clientId, response.submitId);
+    }
+    if (isSendDataWebSocketResponseEventDTO(response)) {
+        return getWebSocketResponseEventKey(exports.WebSocketResponseEvent.SEND_DATA_, clientId, response.dataId);
+    }
+    if (isContestChangesWebSocketResponseEventDTO(response)) {
+        return getWebSocketResponseEventKey(exports.WebSocketResponseEvent.CONTEST_CHANGES, clientId, response.content.contestKey);
+    }
+    if (isProblemCrawledWebSocketResponseEventDTO(response)) {
+        return getWebSocketResponseEventKey(exports.WebSocketResponseEvent.PROBLEM_CRAWLED, clientId, response.content.problemKey);
+    }
+    if (isSubmissionsCrawlWebSocketResponseEventDTO(response)) {
+        return getWebSocketResponseEventKey(exports.WebSocketResponseEvent.SUBMISSIONS_CRAWL, clientId, join([response.content.contestKey, response.content.problemKeys]));
+    }
+    if (isClientTrackWebSocketResponseEventDTO(response)) {
+        // the command is sent to the session channel, `key` holds the targeted client
+        return response.key === clientId ? getWebSocketResponseEventKey(exports.WebSocketResponseEvent.CLIENT_TRACK, clientId, '*') : null;
+    }
+    if (isUserNotificationWebSocketResponseEventDTO(response)) {
+        return getWebSocketResponseEventKey(exports.WebSocketResponseEvent.USER_NOTIFICATION_, clientId, '*');
+    }
+    return null;
+};
+/**
+ * TOPIC channel that the client has to attach to receive the events of a subscription,
+ * or null when the events arrive by the private channels (session / user) the client is always attached to.
+ * Ably rejects the attach if the token has no capability for the channel.
+ */
+const getChannelOfWebSocketSubscribeEvent = (event) => {
+    if (isSubscribeSubmissionRunStatusWebSocketEventDTO(event)) {
+        return CHANNEL_SUBMISSION(event.submitId);
+    }
+    if (isSubscribeProblemCrawledWebSocketEventDTO(event)) {
+        return CHANNEL_PROBLEM(event.problemKey);
+    }
+    if (isSubscribeContestChangesWebSocketEventDTO(event) || isSubscribeSubmissionsCrawlWebSocketEventDTO(event)) {
+        return CHANNEL_CONTEST(event.contestKey, exports.ContestChannelRole.SPECTATORS);
+    }
+    if (isSubscribeClientTrackDataWebSocketEventDTO(event)) {
+        return CHANNEL_CLIENT_TRACK(event.trackedClientId);
+    }
+    return null;
+};
+/**
+ * Contest whose role channels the client needs (the API grants them when the token is requested with this contest).
+ */
+const getContestKeyOfWebSocketSubscribeEvent = (event) => {
+    if (isSubscribeContestChangesWebSocketEventDTO(event) || isSubscribeSubmissionsCrawlWebSocketEventDTO(event)) {
+        return event.contestKey;
+    }
+    return null;
+};
 
 function splitTime(timeRemaining) {
     const remaining = [];
@@ -3350,11 +3493,21 @@ exports.ACCEPTED_PROGRAMMING_LANGUAGES = ACCEPTED_PROGRAMMING_LANGUAGES;
 exports.ASPECT_RATIO = ASPECT_RATIO;
 exports.AssignmentState = AssignmentState;
 exports.AssignmentType = AssignmentType;
+exports.CHANNEL_CLIENT_TRACK = CHANNEL_CLIENT_TRACK;
+exports.CHANNEL_CLIENT_TRACK_ALL = CHANNEL_CLIENT_TRACK_ALL;
+exports.CHANNEL_COMPANY_PRESENCE = CHANNEL_COMPANY_PRESENCE;
+exports.CHANNEL_CONTEST = CHANNEL_CONTEST;
 exports.CHANNEL_PRESENCE_CLIENT = CHANNEL_PRESENCE_CLIENT;
+exports.CHANNEL_PROBLEM = CHANNEL_PROBLEM;
+exports.CHANNEL_PROBLEM_ALL = CHANNEL_PROBLEM_ALL;
 exports.CHANNEL_PUBLISH_MESSAGES = CHANNEL_PUBLISH_MESSAGES;
 exports.CHANNEL_PUBLISH_SUBSCRIPTIONS = CHANNEL_PUBLISH_SUBSCRIPTIONS;
+exports.CHANNEL_SESSION = CHANNEL_SESSION;
+exports.CHANNEL_SUBMISSION = CHANNEL_SUBMISSION;
+exports.CHANNEL_SUBMISSION_ALL = CHANNEL_SUBMISSION_ALL;
 exports.CHANNEL_SUBSCRIBE_CLIENT = CHANNEL_SUBSCRIBE_CLIENT;
 exports.CHANNEL_SUBSCRIBE_NOTIFICATIONS = CHANNEL_SUBSCRIBE_NOTIFICATIONS;
+exports.CHANNEL_USER = CHANNEL_USER;
 exports.CODE_LANGUAGE = CODE_LANGUAGE;
 exports.COMPANY_PLAN = COMPANY_PLAN;
 exports.CONTEST_ROLE = CONTEST_ROLE;
@@ -3459,8 +3612,11 @@ exports.contentsResponse = contentsResponse;
 exports.errorsResponse = errorsResponse;
 exports.getAssignmentCommentKey = getAssignmentCommentKey;
 exports.getAssignmentUserCommentKey = getAssignmentUserCommentKey;
+exports.getChannelOfWebSocketSubscribeEvent = getChannelOfWebSocketSubscribeEvent;
 exports.getClientId = getClientId;
+exports.getContestChannelParams = getContestChannelParams;
 exports.getContestCommentKey = getContestCommentKey;
+exports.getContestKeyOfWebSocketSubscribeEvent = getContestKeyOfWebSocketSubscribeEvent;
 exports.getDataLog = getDataLog;
 exports.getDataOfTestCase = getDataOfTestCase;
 exports.getDays = getDays;
@@ -3482,6 +3638,7 @@ exports.getTotalExercisesOfSummaryWorksheetsInPages = getTotalExercisesOfSummary
 exports.getUserKey = getUserKey;
 exports.getVerdictFromTestCase = getVerdictFromTestCase;
 exports.getWebSocketResponseEventKey = getWebSocketResponseEventKey;
+exports.getWebSocketResponseEventKeyOfResponse = getWebSocketResponseEventKeyOfResponse;
 exports.getWorksheetsInPages = getWorksheetsInPages;
 exports.getYears = getYears;
 exports.humanFileSize = humanFileSize;
@@ -3520,6 +3677,7 @@ exports.isSendDataWebSocketResponseEventDTO = isSendDataWebSocketResponseEventDT
 exports.isStringJson = isStringJson;
 exports.isSubmissionRunStatusMessageWebSocketResponseEventDTO = isSubmissionRunStatusMessageWebSocketResponseEventDTO;
 exports.isSubmissionsCrawlWebSocketResponseEventDTO = isSubmissionsCrawlWebSocketResponseEventDTO;
+exports.isSubscribeClientTrackDataWebSocketEventDTO = isSubscribeClientTrackDataWebSocketEventDTO;
 exports.isSubscribeClientTrackWebSocketEventDTO = isSubscribeClientTrackWebSocketEventDTO;
 exports.isSubscribeCodeRunStatusWebSocketEventDTO = isSubscribeCodeRunStatusWebSocketEventDTO;
 exports.isSubscribeContestChangesWebSocketEventDTO = isSubscribeContestChangesWebSocketEventDTO;
@@ -3529,6 +3687,7 @@ exports.isSubscribeSubmissionRunStatusWebSocketEventDTO = isSubscribeSubmissionR
 exports.isSubscribeSubmissionsCrawlWebSocketEventDTO = isSubscribeSubmissionsCrawlWebSocketEventDTO;
 exports.isSubscribeUserNotificationWebSocketEventDTO = isSubscribeUserNotificationWebSocketEventDTO;
 exports.isTeamMember = isTeamMember;
+exports.isUnsubscribeClientTrackDataWebSocketEventDTO = isUnsubscribeClientTrackDataWebSocketEventDTO;
 exports.isUnsubscribeClientTrackWebSocketEventDTO = isUnsubscribeClientTrackWebSocketEventDTO;
 exports.isUnsubscribeCodeRunStatusWebSocketEventDTO = isUnsubscribeCodeRunStatusWebSocketEventDTO;
 exports.isUnsubscribeContestChangesWebSocketEventDTO = isUnsubscribeContestChangesWebSocketEventDTO;
@@ -3542,6 +3701,7 @@ exports.isUserMessageWebSocketResponseEventDTO = isUserMessageWebSocketResponseE
 exports.isUserNotificationContestClarificationWebSocketResponseEventDTO = isUserNotificationContestClarificationWebSocketResponseEventDTO;
 exports.isUserNotificationSubmissionWebSocketResponseEventDTO = isUserNotificationSubmissionWebSocketResponseEventDTO;
 exports.isUserNotificationWebSocketResponseEventDTO = isUserNotificationWebSocketResponseEventDTO;
+exports.isWebSocketChannelsMessageDTO = isWebSocketChannelsMessageDTO;
 exports.isWebSocketResponseEventDTO = isWebSocketResponseEventDTO;
 exports.isWebsocketSubscription = isWebsocketSubscription;
 exports.isWorksheetAssignment = isWorksheetAssignment;

package/dist/esm/index.js

@@ -580,6 +580,10 @@ var WebSocketMessageEvent;
     WebSocketMessageEvent["CLIENT_TRACK_DEVICE"] = "CLIENT_TRACK_DEVICE";
     WebSocketMessageEvent["CHAT_COMPLETIONS"] = "CHAT_COMPLETIONS";
 })(WebSocketMessageEvent || (WebSocketMessageEvent = {}));
+/**
+ * Subscriptions of the client. With the TOPIC channels they are not sent to the server anymore:
+ * they only say which channel the client attaches (`getChannelOfWebSocketSubscribeEvent`) and the dispatch key.
+ */
 var WebSocketSubscriptionEvent;
 (function (WebSocketSubscriptionEvent) {
     WebSocketSubscriptionEvent["SUBSCRIBE_CODE_RUN_STATUS"] = "SUBSCRIBE_CODE_RUN_STATUS";
@@ -598,6 +602,9 @@ var WebSocketSubscriptionEvent;
     WebSocketSubscriptionEvent["UNSUBSCRIBE_CLIENT_TRACK"] = "UNSUBSCRIBE_CLIENT_TRACK";
     WebSocketSubscriptionEvent["SUBSCRIBE_USER_NOTIFICATION"] = "SUBSCRIBE_USER_NOTIFICATION";
     WebSocketSubscriptionEvent["UNSUBSCRIBE_USER_NOTIFICATION"] = "UNSUBSCRIBE_USER_NOTIFICATION";
+    // an administrator watching the data (screenshots, location, device) sent by another client
+    WebSocketSubscriptionEvent["SUBSCRIBE_CLIENT_TRACK_DATA"] = "SUBSCRIBE_CLIENT_TRACK_DATA";
+    WebSocketSubscriptionEvent["UNSUBSCRIBE_CLIENT_TRACK_DATA"] = "UNSUBSCRIBE_CLIENT_TRACK_DATA";
 })(WebSocketSubscriptionEvent || (WebSocketSubscriptionEvent = {}));
 var WebSocketResponseEvent;
 (function (WebSocketResponseEvent) {
@@ -621,6 +628,20 @@ var WebSocketResponseEvent;
     WebSocketResponseEvent["USER_NOTIFICATION_SUBMISSION"] = "USER_NOTIFICATION_SUBMISSION";
     WebSocketResponseEvent["USER_NOTIFICATION_CONTEST_CLARIFICATION"] = "USER_NOTIFICATION_CONTEST_CLARIFICATION";
 })(WebSocketResponseEvent || (WebSocketResponseEvent = {}));
+/**
+ * Roles of a contest, with the same names as the contest members in the DB.
+ * Each role has its own Ably channel: `contest:{contestKey}:{role}` (see `CHANNEL_CONTEST`).
+ * The inclusions follow `getContestAccessPermissions`:
+ *   spectators ⊇ managers ⊇ administrators, spectators ⊇ participants, spectators ⊇ guests
+ */
+var ContestChannelRole;
+(function (ContestChannelRole) {
+    ContestChannelRole["ADMINISTRATORS"] = "administrators";
+    ContestChannelRole["MANAGERS"] = "managers";
+    ContestChannelRole["PARTICIPANTS"] = "participants";
+    ContestChannelRole["GUESTS"] = "guests";
+    ContestChannelRole["SPECTATORS"] = "spectators";
+})(ContestChannelRole || (ContestChannelRole = {}));
 
 var DataViewMode;
 (function (DataViewMode) {
@@ -2221,11 +2242,56 @@ const EMPTY_USER_PERMISSIONS = {
     },
 };
 
+// LEGACY channels (fan-out per client through the subscriptions registry in Redis)
+/** @deprecated the subscriptions registry was replaced by the TOPIC channels granted in the Ably token */
 const CHANNEL_PUBLISH_SUBSCRIPTIONS = 'pub:subscriptions';
+/** @deprecated not used, the events arrive by the TOPIC channels */
 const CHANNEL_SUBSCRIBE_NOTIFICATIONS = 'sub:notifications';
+/** @deprecated the events arrive by the TOPIC channels */
 const CHANNEL_SUBSCRIBE_CLIENT = (clientId) => `sub:client:${clientId}`;
+/** messages from the clients to the backend (chat completions, client track screenshots) */
 const CHANNEL_PUBLISH_MESSAGES = 'pub:messages';
+/** @deprecated global presence channel (limited to 200 members by Ably), replaced by CHANNEL_COMPANY_PRESENCE */
 const CHANNEL_PRESENCE_CLIENT = 'pre:client';
+// TOPIC channels
+// The backend publishes each event once on the channel of its topic and Ably does the fan-out.
+// Who can subscribe to each channel is decided by the API in the Ably token (capability), never by the client.
+// Dynamic segments are encoded so a key can never inject a `:` (the Ably segment separator used by the wildcards).
+const segment = (value) => encodeURIComponent(value);
+/** private: events of one session (code runs, requested data, client track commands) */
+const CHANNEL_SESSION = (sessionId) => `session:${segment(sessionId)}`;
+/** private: events of one user (own submissions while the contest is frozen, notifications) */
+const CHANNEL_USER = (userId) => `user:${segment(userId)}`;
+/** public: status of a submission when it is visible to everyone */
+const CHANNEL_SUBMISSION = (submitId) => `submission:${segment(submitId)}`;
+/** public: changes of a problem */
+const CHANNEL_PROBLEM = (problemKey) => `problem:${segment(problemKey)}`;
+/** per role: events of a contest for one role (and the roles above it, see `ContestChannelRole`) */
+const CHANNEL_CONTEST = (contestKey, role) => `contest:${segment(contestKey)}:${role}`;
+/** system administrators only: data sent by a tracked client (screenshots, location, device) */
+const CHANNEL_CLIENT_TRACK = (trackedClientId) => `client-track:${segment(trackedClientId)}`;
+/**
+ * presence of the clients (tabs) of the logged users of a company (by its key), data: `UserPresenceData`.
+ * The clients only enter (capability `presence`), only the administrators of the company receive it
+ * (capability `presence-subscribe`). Ably limits the presence members per channel (200 by default,
+ * more with server-side batching enabled on the `presence` namespace).
+ * The identity of a member is its `clientId` (`sessionId|uiId`, verified by Ably), never its data.
+ */
+const CHANNEL_COMPANY_PRESENCE = (companyKey) => `presence:company:${segment(companyKey)}`;
+// capability resources (wildcards) of the public channels
+const CHANNEL_SUBMISSION_ALL = 'submission:*';
+const CHANNEL_PROBLEM_ALL = 'problem:*';
+const CHANNEL_CLIENT_TRACK_ALL = 'client-track:*';
+/**
+ * Returns the contest and role of a `CHANNEL_CONTEST` channel name, or null if it is not one.
+ */
+const getContestChannelParams = (channel) => {
+    const [namespace, contestKey, role, ...rest] = channel.split(':');
+    if (namespace !== 'contest' || !contestKey || rest.length || !Object.values(ContestChannelRole).includes(role)) {
+        return null;
+    }
+    return { contestKey: decodeURIComponent(contestKey), role: role };
+};
 
 const NEW_PAGE_SHEET = () => ({
     id: v4(),
@@ -3008,6 +3074,16 @@ const isUnsubscribeUserNotificationWebSocketEventDTO = (event) => {
     return isWebsocketSubscription(event)
         && event?.event === WebSocketSubscriptionEvent.UNSUBSCRIBE_USER_NOTIFICATION;
 };
+const isSubscribeClientTrackDataWebSocketEventDTO = (event) => {
+    return isWebsocketSubscription(event)
+        && event?.event === WebSocketSubscriptionEvent.SUBSCRIBE_CLIENT_TRACK_DATA
+        && typeof event?.trackedClientId === 'string' && !!event.trackedClientId;
+};
+const isUnsubscribeClientTrackDataWebSocketEventDTO = (event) => {
+    return isWebsocketSubscription(event)
+        && event?.event === WebSocketSubscriptionEvent.UNSUBSCRIBE_CLIENT_TRACK_DATA
+        && typeof event?.trackedClientId === 'string' && !!event.trackedClientId;
+};
 // is WebSocketResponseEventDTO, CHANNEL_SUBSCRIBE_CLIENT
 const isWebSocketResponseEventDTO = (event) => {
     return Object.values(WebSocketResponseEvent).includes(event?.event)
@@ -3121,6 +3197,73 @@ const isUserNotificationContestClarificationWebSocketResponseEventDTO = (event)
 const getWebSocketResponseEventKey = (event, clientId, id) => {
     return `${event}-${clientId}-${id}`;
 };
+const isWebSocketChannelsMessageDTO = (message) => {
+    return Array.isArray(message?.channels)
+        && message.channels.every((channel) => typeof channel === 'string' && !!channel)
+        && Object.values(WebSocketResponseEvent).includes(message?.event?.event);
+};
+/**
+ * Key used by the client to dispatch a response received on a TOPIC channel to its subscribers.
+ * It is the same key that `getKeyWebSocketEventDTO` (base-ui) computes for the subscription.
+ * Returns null when the response is not addressed to this client.
+ */
+const getWebSocketResponseEventKeyOfResponse = (response, clientId) => {
+    if (isCodeRunStatusMessageWebSocketResponseEventDTO(response)) {
+        return getWebSocketResponseEventKey(WebSocketResponseEvent.CODE_RUN_STATUS, clientId, response.runId);
+    }
+    if (isSubmissionRunStatusMessageWebSocketResponseEventDTO(response)) {
+        return getWebSocketResponseEventKey(WebSocketResponseEvent.SUBMISSION_RUN_STATUS, clientId, response.submitId);
+    }
+    if (isSendDataWebSocketResponseEventDTO(response)) {
+        return getWebSocketResponseEventKey(WebSocketResponseEvent.SEND_DATA_, clientId, response.dataId);
+    }
+    if (isContestChangesWebSocketResponseEventDTO(response)) {
+        return getWebSocketResponseEventKey(WebSocketResponseEvent.CONTEST_CHANGES, clientId, response.content.contestKey);
+    }
+    if (isProblemCrawledWebSocketResponseEventDTO(response)) {
+        return getWebSocketResponseEventKey(WebSocketResponseEvent.PROBLEM_CRAWLED, clientId, response.content.problemKey);
+    }
+    if (isSubmissionsCrawlWebSocketResponseEventDTO(response)) {
+        return getWebSocketResponseEventKey(WebSocketResponseEvent.SUBMISSIONS_CRAWL, clientId, join([response.content.contestKey, response.content.problemKeys]));
+    }
+    if (isClientTrackWebSocketResponseEventDTO(response)) {
+        // the command is sent to the session channel, `key` holds the targeted client
+        return response.key === clientId ? getWebSocketResponseEventKey(WebSocketResponseEvent.CLIENT_TRACK, clientId, '*') : null;
+    }
+    if (isUserNotificationWebSocketResponseEventDTO(response)) {
+        return getWebSocketResponseEventKey(WebSocketResponseEvent.USER_NOTIFICATION_, clientId, '*');
+    }
+    return null;
+};
+/**
+ * TOPIC channel that the client has to attach to receive the events of a subscription,
+ * or null when the events arrive by the private channels (session / user) the client is always attached to.
+ * Ably rejects the attach if the token has no capability for the channel.
+ */
+const getChannelOfWebSocketSubscribeEvent = (event) => {
+    if (isSubscribeSubmissionRunStatusWebSocketEventDTO(event)) {
+        return CHANNEL_SUBMISSION(event.submitId);
+    }
+    if (isSubscribeProblemCrawledWebSocketEventDTO(event)) {
+        return CHANNEL_PROBLEM(event.problemKey);
+    }
+    if (isSubscribeContestChangesWebSocketEventDTO(event) || isSubscribeSubmissionsCrawlWebSocketEventDTO(event)) {
+        return CHANNEL_CONTEST(event.contestKey, ContestChannelRole.SPECTATORS);
+    }
+    if (isSubscribeClientTrackDataWebSocketEventDTO(event)) {
+        return CHANNEL_CLIENT_TRACK(event.trackedClientId);
+    }
+    return null;
+};
+/**
+ * Contest whose role channels the client needs (the API grants them when the token is requested with this contest).
+ */
+const getContestKeyOfWebSocketSubscribeEvent = (event) => {
+    if (isSubscribeContestChangesWebSocketEventDTO(event) || isSubscribeSubmissionsCrawlWebSocketEventDTO(event)) {
+        return event.contestKey;
+    }
+    return null;
+};
 
 function splitTime(timeRemaining) {
     const remaining = [];
@@ -3344,4 +3487,4 @@ const isQuizTextSheet = (value) => {
         && ['text', 'number', 'textarea'].includes(value?.inputType);
 };
 
-export { ACCEPTED_PROGRAMMING_LANGUAGES, ASPECT_RATIO, AspectRatio, AssignmentClass, AssignmentState, AssignmentType, CHANNEL_PRESENCE_CLIENT, CHANNEL_PUBLISH_MESSAGES, CHANNEL_PUBLISH_SUBSCRIPTIONS, CHANNEL_SUBSCRIBE_CLIENT, CHANNEL_SUBSCRIBE_NOTIFICATIONS, CODE_LANGUAGE, COMPANY_PLAN, CONTEST_ROLE, CONTEST_STATUS, COOKIE_JUKI_SESSION_ID, COURSE_ROLE, CodeLanguage, CollectionKey, CompanyLogoType, CompanyPlan, ContestEventAction, ContestProblemBlockedByType, ContestProblemPrerequisiteType, ContestStatus, ContestTimeStatus, CourseRole, CourseStatus, CourseType, DAY_NAMES, DEFAULT_JUKI_PROFILE_IMAGE, DataViewMode, EMPTY_DOCUMENT_MEMBERS, EMPTY_ENTITY_MEMBERS, EMPTY_USER_PERMISSIONS, ENTITY_ACCESS, ENTITY_STATE, ERROR, EmailSubscription, EmailValidationState, EntityAccess, EntityCollection, EntityMembersRank, EntityState, EntityStatus, ErrorCode, FILE_ROLE, FILE_TYPE, FileMemberRole, FileType, FilesJukiPub, GroupType, HEADER_JUKI_FORWARDED_HOST, HEADER_JUKI_INTERNAL_API_KEY, HEADER_JUKI_METADATA, HEADER_JUKI_SECRET_TOKEN, HEADER_JUKI_VISITOR_SESSION_ID, HOURS, HTTPMethod, JUDGE, JUKI_APP_COMPANY_KEY, JUKI_APP_EMAIL_TEMPLATE, JkError, Judge, LANGUAGE, LOWERCASE_LETTERS, Language, LogLevel, LogOperation, MAX_DATE, MEMBER_ROLE, MILLISECONDS, MINUTES, MIN_DATE, MONTH_NAMES, MemberRole, MemberType, MenuViewMode, NEW_PAGE_SHEET, NUMBERS, NotificationType, ONE_DAY, ONE_HOUR, ONE_MINUTE, ONE_SECOND, ONE_WEEK, PAGE, PAGE_SIZE, PAGE_SIZES, PALLETE, PROBLEM_INPUT, PROBLEM_MODE, PROBLEM_MODES, PROBLEM_OUTPUT, PROBLEM_ROLE, PROBLEM_TYPE, PROBLEM_TYPES, PROBLEM_VERDICT, PROBLEM_VERDICTS, ProblemInput, ProblemOutput, ProblemScoringMode, ProblemType, ProblemVerdict, ProfileSetting, QuizScoringMode, RUNNER_ACCEPTED_PROBLEM_MODES, RUNNER_ACCEPTED_PROBLEM_TYPES, RUNNER_ACCEPTED_PROGRAMMING_LANGUAGES, RUNNER_TYPE, Role, RunnerType, SECONDS, SEC_120, SEC_30, SEC_60, SEC_90, SEPARATOR_TOKEN, SUBMISSION_RUN_STATUS, SUPPORT_EMAIL, SYSTEM_ROLE, ScopeData, Status, SubmissionRunStatus, SystemRole, TEAM_ROLE, THEME, TeamRole, TeamStatus, Theme, TypeTestCase, UPPERCASE_LETTERS, USER_ROLE, USER_STATUS, UserRole, UserStatus, UserTeamStatus, WebSocketMessageEvent, WebSocketResponseEvent, WebSocketSubscriptionEvent, WorkingIn, WorksheetType, YEARS, _KEY, _SUB_SUB_TAB, _SUB_TAB, _TAB, _TYPE, areArraysDifferent, chunkString, cleanRequest, clearAsyncInterval, consoleError, consoleInfo, consoleWarn, contentResponse, contentsResponse, errorsResponse, getAssignmentCommentKey, getAssignmentUserCommentKey, getClientId, getContestCommentKey, getDataLog, getDataOfTestCase, getDays, getDefaultMeta, getDocumentAccess, getHours, getMilliseconds, getMinutes, getMonths, getParamsOfClientId, getParamsOfUserKey, getPlainText, getProblemCommentKey, getProblemJudgeKey, getRandomString, getSeconds, getSummaryWorksheetsInPages, getTotalExercisesOfSummaryWorksheetsInPages, getUserKey, getVerdictFromTestCase, getWebSocketResponseEventKey, getWorksheetsInPages, getYears, humanFileSize, indexToLetters, isBasicWorksheet, isChatCompletionsWebSocketEventDTO, isClientTrackDeviceWebSocketEventDTO, isClientTrackLocationWebSocketEventDTO, isClientTrackScreenshotWebSocketEventDTO, isClientTrackWebSocketResponseEventDTO, isCodeEditorSheet, isCodeRunStatusMessageWebSocketResponseEventDTO, isContestAssignment, isContestChangesWebSocketResponseEventDTO, isCourseAssignment, isEndlessContest, isFutureContest, isGlobalContest, isJkmdSheet, isObjectJson, isPastContest, isPingWebSocketEventDTO, isPongWebSocketResponseEventDTO, isProblemCrawledWebSocketResponseEventDTO, isQuizOptionsSheet, isQuizProblemSheet, isQuizTextSheet, isSenDataChatCompletionsWebSocketResponseEventDTO, isSendDataClientTrackWebSocketResponseEventDTO, isSendDataEc2InstancesListWebSocketResponseEventDTO, isSendDataEcsTaskDefinitionListWebSocketResponseEventDTO, isSendDataEcsTasksListWebSocketResponseEventDTO, isSendDataRunCommandWebSocketResponseEventDTO, isSendDataSsmSessionsListWebSocketResponseEventDTO, isSendDataWebSocketResponseEventDTO, isStringJson, isSubmissionRunStatusMessageWebSocketResponseEventDTO, isSubmissionsCrawlWebSocketResponseEventDTO, isSubscribeClientTrackWebSocketEventDTO, isSubscribeCodeRunStatusWebSocketEventDTO, isSubscribeContestChangesWebSocketEventDTO, isSubscribeGetDataWebSocketEventDTO, isSubscribeProblemCrawledWebSocketEventDTO, isSubscribeSubmissionRunStatusWebSocketEventDTO, isSubscribeSubmissionsCrawlWebSocketEventDTO, isSubscribeUserNotificationWebSocketEventDTO, isTeamMember, isUnsubscribeClientTrackWebSocketEventDTO, isUnsubscribeCodeRunStatusWebSocketEventDTO, isUnsubscribeContestChangesWebSocketEventDTO, isUnsubscribeGetDataWebSocketEventDTO, isUnsubscribeProblemCrawledWebSocketEventDTO, isUnsubscribeSubmissionRunStatusWebSocketEventDTO, isUnsubscribeSubmissionsCrawlWebSocketEventDTO, isUnsubscribeUserNotificationWebSocketEventDTO, isUserMember, isUserMessageWebSocketResponseEventDTO, isUserNotificationContestClarificationWebSocketResponseEventDTO, isUserNotificationSubmissionWebSocketResponseEventDTO, isUserNotificationWebSocketResponseEventDTO, isWebSocketResponseEventDTO, isWebsocketSubscription, isWorksheetAssignment, join, lettersToIndex, memorySizeOf, mergeVerdicts, mex, normalizeToLocalStartOfDay, normalizeToLocalStartOfHour, normalizeToLocalStartOfMinutes, normalizeToLocalStartOfSeconds, objectUpdate, objectsUpdate, range, removeExtension, safeJsonParse, setAsyncInterval, split, splitTime, stringToArrayBuffer, toEntityMembersDTO, toJkError };
+export { ACCEPTED_PROGRAMMING_LANGUAGES, ASPECT_RATIO, AspectRatio, AssignmentClass, AssignmentState, AssignmentType, CHANNEL_CLIENT_TRACK, CHANNEL_CLIENT_TRACK_ALL, CHANNEL_COMPANY_PRESENCE, CHANNEL_CONTEST, CHANNEL_PRESENCE_CLIENT, CHANNEL_PROBLEM, CHANNEL_PROBLEM_ALL, CHANNEL_PUBLISH_MESSAGES, CHANNEL_PUBLISH_SUBSCRIPTIONS, CHANNEL_SESSION, CHANNEL_SUBMISSION, CHANNEL_SUBMISSION_ALL, CHANNEL_SUBSCRIBE_CLIENT, CHANNEL_SUBSCRIBE_NOTIFICATIONS, CHANNEL_USER, CODE_LANGUAGE, COMPANY_PLAN, CONTEST_ROLE, CONTEST_STATUS, COOKIE_JUKI_SESSION_ID, COURSE_ROLE, CodeLanguage, CollectionKey, CompanyLogoType, CompanyPlan, ContestChannelRole, ContestEventAction, ContestProblemBlockedByType, ContestProblemPrerequisiteType, ContestStatus, ContestTimeStatus, CourseRole, CourseStatus, CourseType, DAY_NAMES, DEFAULT_JUKI_PROFILE_IMAGE, DataViewMode, EMPTY_DOCUMENT_MEMBERS, EMPTY_ENTITY_MEMBERS, EMPTY_USER_PERMISSIONS, ENTITY_ACCESS, ENTITY_STATE, ERROR, EmailSubscription, EmailValidationState, EntityAccess, EntityCollection, EntityMembersRank, EntityState, EntityStatus, ErrorCode, FILE_ROLE, FILE_TYPE, FileMemberRole, FileType, FilesJukiPub, GroupType, HEADER_JUKI_FORWARDED_HOST, HEADER_JUKI_INTERNAL_API_KEY, HEADER_JUKI_METADATA, HEADER_JUKI_SECRET_TOKEN, HEADER_JUKI_VISITOR_SESSION_ID, HOURS, HTTPMethod, JUDGE, JUKI_APP_COMPANY_KEY, JUKI_APP_EMAIL_TEMPLATE, JkError, Judge, LANGUAGE, LOWERCASE_LETTERS, Language, LogLevel, LogOperation, MAX_DATE, MEMBER_ROLE, MILLISECONDS, MINUTES, MIN_DATE, MONTH_NAMES, MemberRole, MemberType, MenuViewMode, NEW_PAGE_SHEET, NUMBERS, NotificationType, ONE_DAY, ONE_HOUR, ONE_MINUTE, ONE_SECOND, ONE_WEEK, PAGE, PAGE_SIZE, PAGE_SIZES, PALLETE, PROBLEM_INPUT, PROBLEM_MODE, PROBLEM_MODES, PROBLEM_OUTPUT, PROBLEM_ROLE, PROBLEM_TYPE, PROBLEM_TYPES, PROBLEM_VERDICT, PROBLEM_VERDICTS, ProblemInput, ProblemOutput, ProblemScoringMode, ProblemType, ProblemVerdict, ProfileSetting, QuizScoringMode, RUNNER_ACCEPTED_PROBLEM_MODES, RUNNER_ACCEPTED_PROBLEM_TYPES, RUNNER_ACCEPTED_PROGRAMMING_LANGUAGES, RUNNER_TYPE, Role, RunnerType, SECONDS, SEC_120, SEC_30, SEC_60, SEC_90, SEPARATOR_TOKEN, SUBMISSION_RUN_STATUS, SUPPORT_EMAIL, SYSTEM_ROLE, ScopeData, Status, SubmissionRunStatus, SystemRole, TEAM_ROLE, THEME, TeamRole, TeamStatus, Theme, TypeTestCase, UPPERCASE_LETTERS, USER_ROLE, USER_STATUS, UserRole, UserStatus, UserTeamStatus, WebSocketMessageEvent, WebSocketResponseEvent, WebSocketSubscriptionEvent, WorkingIn, WorksheetType, YEARS, _KEY, _SUB_SUB_TAB, _SUB_TAB, _TAB, _TYPE, areArraysDifferent, chunkString, cleanRequest, clearAsyncInterval, consoleError, consoleInfo, consoleWarn, contentResponse, contentsResponse, errorsResponse, getAssignmentCommentKey, getAssignmentUserCommentKey, getChannelOfWebSocketSubscribeEvent, getClientId, getContestChannelParams, getContestCommentKey, getContestKeyOfWebSocketSubscribeEvent, getDataLog, getDataOfTestCase, getDays, getDefaultMeta, getDocumentAccess, getHours, getMilliseconds, getMinutes, getMonths, getParamsOfClientId, getParamsOfUserKey, getPlainText, getProblemCommentKey, getProblemJudgeKey, getRandomString, getSeconds, getSummaryWorksheetsInPages, getTotalExercisesOfSummaryWorksheetsInPages, getUserKey, getVerdictFromTestCase, getWebSocketResponseEventKey, getWebSocketResponseEventKeyOfResponse, getWorksheetsInPages, getYears, humanFileSize, indexToLetters, isBasicWorksheet, isChatCompletionsWebSocketEventDTO, isClientTrackDeviceWebSocketEventDTO, isClientTrackLocationWebSocketEventDTO, isClientTrackScreenshotWebSocketEventDTO, isClientTrackWebSocketResponseEventDTO, isCodeEditorSheet, isCodeRunStatusMessageWebSocketResponseEventDTO, isContestAssignment, isContestChangesWebSocketResponseEventDTO, isCourseAssignment, isEndlessContest, isFutureContest, isGlobalContest, isJkmdSheet, isObjectJson, isPastContest, isPingWebSocketEventDTO, isPongWebSocketResponseEventDTO, isProblemCrawledWebSocketResponseEventDTO, isQuizOptionsSheet, isQuizProblemSheet, isQuizTextSheet, isSenDataChatCompletionsWebSocketResponseEventDTO, isSendDataClientTrackWebSocketResponseEventDTO, isSendDataEc2InstancesListWebSocketResponseEventDTO, isSendDataEcsTaskDefinitionListWebSocketResponseEventDTO, isSendDataEcsTasksListWebSocketResponseEventDTO, isSendDataRunCommandWebSocketResponseEventDTO, isSendDataSsmSessionsListWebSocketResponseEventDTO, isSendDataWebSocketResponseEventDTO, isStringJson, isSubmissionRunStatusMessageWebSocketResponseEventDTO, isSubmissionsCrawlWebSocketResponseEventDTO, isSubscribeClientTrackDataWebSocketEventDTO, isSubscribeClientTrackWebSocketEventDTO, isSubscribeCodeRunStatusWebSocketEventDTO, isSubscribeContestChangesWebSocketEventDTO, isSubscribeGetDataWebSocketEventDTO, isSubscribeProblemCrawledWebSocketEventDTO, isSubscribeSubmissionRunStatusWebSocketEventDTO, isSubscribeSubmissionsCrawlWebSocketEventDTO, isSubscribeUserNotificationWebSocketEventDTO, isTeamMember, isUnsubscribeClientTrackDataWebSocketEventDTO, isUnsubscribeClientTrackWebSocketEventDTO, isUnsubscribeCodeRunStatusWebSocketEventDTO, isUnsubscribeContestChangesWebSocketEventDTO, isUnsubscribeGetDataWebSocketEventDTO, isUnsubscribeProblemCrawledWebSocketEventDTO, isUnsubscribeSubmissionRunStatusWebSocketEventDTO, isUnsubscribeSubmissionsCrawlWebSocketEventDTO, isUnsubscribeUserNotificationWebSocketEventDTO, isUserMember, isUserMessageWebSocketResponseEventDTO, isUserNotificationContestClarificationWebSocketResponseEventDTO, isUserNotificationSubmissionWebSocketResponseEventDTO, isUserNotificationWebSocketResponseEventDTO, isWebSocketChannelsMessageDTO, isWebSocketResponseEventDTO, isWebsocketSubscription, isWorksheetAssignment, join, lettersToIndex, memorySizeOf, mergeVerdicts, mex, normalizeToLocalStartOfDay, normalizeToLocalStartOfHour, normalizeToLocalStartOfMinutes, normalizeToLocalStartOfSeconds, objectUpdate, objectsUpdate, range, removeExtension, safeJsonParse, setAsyncInterval, split, splitTime, stringToArrayBuffer, toEntityMembersDTO, toJkError };

package/dist/types/constants/websocket.d.ts

@@ -1,6 +1,41 @@
-import { ClientId } from '../types';
+import { ClientId, ContestChannelRole } from '../types';
+/** @deprecated the subscriptions registry was replaced by the TOPIC channels granted in the Ably token */
 export declare const CHANNEL_PUBLISH_SUBSCRIPTIONS = "pub:subscriptions";
+/** @deprecated not used, the events arrive by the TOPIC channels */
 export declare const CHANNEL_SUBSCRIBE_NOTIFICATIONS = "sub:notifications";
+/** @deprecated the events arrive by the TOPIC channels */
 export declare const CHANNEL_SUBSCRIBE_CLIENT: (clientId: ClientId) => string;
+/** messages from the clients to the backend (chat completions, client track screenshots) */
 export declare const CHANNEL_PUBLISH_MESSAGES = "pub:messages";
+/** @deprecated global presence channel (limited to 200 members by Ably), replaced by CHANNEL_COMPANY_PRESENCE */
 export declare const CHANNEL_PRESENCE_CLIENT = "pre:client";
+/** private: events of one session (code runs, requested data, client track commands) */
+export declare const CHANNEL_SESSION: (sessionId: string) => string;
+/** private: events of one user (own submissions while the contest is frozen, notifications) */
+export declare const CHANNEL_USER: (userId: string) => string;
+/** public: status of a submission when it is visible to everyone */
+export declare const CHANNEL_SUBMISSION: (submitId: string) => string;
+/** public: changes of a problem */
+export declare const CHANNEL_PROBLEM: (problemKey: string) => string;
+/** per role: events of a contest for one role (and the roles above it, see `ContestChannelRole`) */
+export declare const CHANNEL_CONTEST: (contestKey: string, role: ContestChannelRole) => string;
+/** system administrators only: data sent by a tracked client (screenshots, location, device) */
+export declare const CHANNEL_CLIENT_TRACK: (trackedClientId: ClientId) => string;
+/**
+ * presence of the clients (tabs) of the logged users of a company (by its key), data: `UserPresenceData`.
+ * The clients only enter (capability `presence`), only the administrators of the company receive it
+ * (capability `presence-subscribe`). Ably limits the presence members per channel (200 by default,
+ * more with server-side batching enabled on the `presence` namespace).
+ * The identity of a member is its `clientId` (`sessionId|uiId`, verified by Ably), never its data.
+ */
+export declare const CHANNEL_COMPANY_PRESENCE: (companyKey: string) => string;
+export declare const CHANNEL_SUBMISSION_ALL = "submission:*";
+export declare const CHANNEL_PROBLEM_ALL = "problem:*";
+export declare const CHANNEL_CLIENT_TRACK_ALL = "client-track:*";
+/**
+ * Returns the contest and role of a `CHANNEL_CONTEST` channel name, or null if it is not one.
+ */
+export declare const getContestChannelParams: (channel: string) => {
+    contestKey: string;
+    role: ContestChannelRole;
+} | null;

package/dist/types/dto/socket.d.ts

@@ -8,6 +8,7 @@ interface WebsocketMessage {
 export interface PingWebSocketEventDTO extends WebsocketMessage {
     event: WebSocketMessageEvent.PING;
 }
+/** @deprecated the location is the `href` of the company presence (`UserPresenceData`) */
 export interface ClientTrackLocationWebSocketEventDTO extends WebsocketMessage {
     event: WebSocketMessageEvent.CLIENT_TRACK_LOCATION;
     href: string;
@@ -94,8 +95,16 @@ export interface UnsubscribeUserNotificationWebSocketEventDTO extends WebsocketS
     event: WebSocketSubscriptionEvent.UNSUBSCRIBE_USER_NOTIFICATION;
     userKey: string;
 }
-export type WebSocketSubscribeEventDTO = SubscribeCodeRunStatusWebSocketEventDTO | SubscribeSubmissionRunStatusWebSocketEventDTO | SubscribeGetDataWebSocketEventDTO | SubscribeProblemCrawledWebSocketEventDTO | SubscribeSubmissionsCrawlWebSocketEventDTO | SubscribeContestChangesWebSocketEventDTO | SubscribeClientTrackWebSocketEventDTO | SubscribeUserNotificationWebsocketEventDTO;
-export type WebSocketUnsubscribeEventDTO = UnsubscribeCodeRunStatusWebSocketEventDTO | UnsubscribeSubmissionRunStatusWebSocketEventDTO | UnsubscribeGetDataWebSocketEventDTO | UnsubscribeProblemCrawledWebSocketEventDTO | UnsubscribeSubmissionsCrawlWebSocketEventDTO | UnsubscribeContestChangesWebSocketEventDTO | UnsubscribeClientTrackWebSocketEventDTO | UnsubscribeUserNotificationWebSocketEventDTO;
+export interface SubscribeClientTrackDataWebSocketEventDTO extends WebsocketSubscription {
+    event: WebSocketSubscriptionEvent.SUBSCRIBE_CLIENT_TRACK_DATA;
+    trackedClientId: ClientId;
+}
+export interface UnsubscribeClientTrackDataWebSocketEventDTO extends WebsocketSubscription {
+    event: WebSocketSubscriptionEvent.UNSUBSCRIBE_CLIENT_TRACK_DATA;
+    trackedClientId: ClientId;
+}
+export type WebSocketSubscribeEventDTO = SubscribeCodeRunStatusWebSocketEventDTO | SubscribeSubmissionRunStatusWebSocketEventDTO | SubscribeGetDataWebSocketEventDTO | SubscribeProblemCrawledWebSocketEventDTO | SubscribeSubmissionsCrawlWebSocketEventDTO | SubscribeContestChangesWebSocketEventDTO | SubscribeClientTrackWebSocketEventDTO | SubscribeUserNotificationWebsocketEventDTO | SubscribeClientTrackDataWebSocketEventDTO;
+export type WebSocketUnsubscribeEventDTO = UnsubscribeCodeRunStatusWebSocketEventDTO | UnsubscribeSubmissionRunStatusWebSocketEventDTO | UnsubscribeGetDataWebSocketEventDTO | UnsubscribeProblemCrawledWebSocketEventDTO | UnsubscribeSubmissionsCrawlWebSocketEventDTO | UnsubscribeContestChangesWebSocketEventDTO | UnsubscribeClientTrackWebSocketEventDTO | UnsubscribeUserNotificationWebSocketEventDTO | UnsubscribeClientTrackDataWebSocketEventDTO;
 export interface WebSocketResponse {
     event: WebSocketResponseEvent;
     key: WebSocketResponseEventKey;
@@ -253,4 +262,20 @@ export interface UserNotificationContestClarificationWebSocketResponseEventDTO e
     };
 }
 export type WebSocketResponseEventDTO = PongWebSocketResponseEventDTO | CodeRunStatusWebSocketResponseEventDTO | SubmissionRunStatusWebSocketResponseEventDTO | UserMessageWebSocketResponseEventDTO | SendDataEcsTaskDefinitionListWebSocketResponseEventDTO | SendDataEcsTasksListWebSocketResponseEventDTO | SendDataEc2InstancesListWebSocketResponseEventDTO | SendDataSsmSessionsListWebSocketResponseEventDTO | ProblemCrawledWebSocketResponseEventDTO | SendDataChatCompletionsWebSocketResponseEventDTO | SubmissionsCrawlWebSocketResponseEventDTO | ContestChangesWebSocketResponseEventDTO | SendDataRunCommandWebSocketResponseEventDTO | SendDataClientTrackWebSocketResponseEventDTO | ClientTrackWebSocketResponseEventDTO | UserNotificationSubmissionWebSocketResponseEventDTO | UserNotificationContestClarificationWebSocketResponseEventDTO;
+/**
+ * Message sent by the backend producers to the websocket SQS queue:
+ * the producer (trusted, with access to the DB) decides the Ably channels where the event is published.
+ */
+export interface WebSocketChannelsMessageDTO {
+    channels: string[];
+    event: WebSocketResponseEventDTO;
+}
+/**
+ * Data of a client (tab) in its company presence channel (`CHANNEL_COMPANY_PRESENCE`).
+ * Sent by the client: informative only, the identity is the presence member `clientId`.
+ */
+export interface UserPresenceData {
+    href: string;
+    uiId: string;
+}
 export {};

package/dist/types/helpers/socket.d.ts

@@ -1,4 +1,4 @@
-import { ChatCompletionsWebSocketEventDTO, ClientTrackDeviceWebSocketEventDTO, ClientTrackLocationWebSocketEventDTO, ClientTrackScreenshotWebSocketEventDTO, ClientTrackWebSocketResponseEventDTO, CodeRunStatusWebSocketResponseEventDTO, ContestChangesWebSocketResponseEventDTO, PingWebSocketEventDTO, PongWebSocketResponseEventDTO, ProblemCrawledWebSocketResponseEventDTO, SendDataChatCompletionsWebSocketResponseEventDTO, SendDataClientTrackWebSocketResponseEventDTO, SendDataEc2InstancesListWebSocketResponseEventDTO, SendDataEcsTaskDefinitionListWebSocketResponseEventDTO, SendDataEcsTasksListWebSocketResponseEventDTO, SendDataRunCommandWebSocketResponseEventDTO, SendDataSsmSessionsListWebSocketResponseEventDTO, SendDataWebSocketResponseEventDTO, SubmissionRunStatusWebSocketResponseEventDTO, SubmissionsCrawlWebSocketResponseEventDTO, SubscribeClientTrackWebSocketEventDTO, SubscribeCodeRunStatusWebSocketEventDTO, SubscribeContestChangesWebSocketEventDTO, SubscribeGetDataWebSocketEventDTO, SubscribeProblemCrawledWebSocketEventDTO, SubscribeSubmissionRunStatusWebSocketEventDTO, SubscribeSubmissionsCrawlWebSocketEventDTO, SubscribeUserNotificationWebsocketEventDTO, UnsubscribeClientTrackWebSocketEventDTO, UnsubscribeCodeRunStatusWebSocketEventDTO, UnsubscribeContestChangesWebSocketEventDTO, UnsubscribeGetDataWebSocketEventDTO, UnsubscribeProblemCrawledWebSocketEventDTO, UnsubscribeSubmissionRunStatusWebSocketEventDTO, UnsubscribeSubmissionsCrawlWebSocketEventDTO, UnsubscribeUserNotificationWebSocketEventDTO, UserMessageWebSocketResponseEventDTO, UserNotificationContestClarificationWebSocketResponseEventDTO, UserNotificationSubmissionWebSocketResponseEventDTO, UserNotificationWebSocketResponseEventDTO, WebSocketMessageEventDTO, WebSocketResponseEventDTO, WebSocketSubscribeEventDTO, WebSocketUnsubscribeEventDTO } from '../dto';
+import { ChatCompletionsWebSocketEventDTO, ClientTrackDeviceWebSocketEventDTO, ClientTrackLocationWebSocketEventDTO, ClientTrackScreenshotWebSocketEventDTO, ClientTrackWebSocketResponseEventDTO, CodeRunStatusWebSocketResponseEventDTO, ContestChangesWebSocketResponseEventDTO, PingWebSocketEventDTO, PongWebSocketResponseEventDTO, ProblemCrawledWebSocketResponseEventDTO, SendDataChatCompletionsWebSocketResponseEventDTO, SendDataClientTrackWebSocketResponseEventDTO, SendDataEc2InstancesListWebSocketResponseEventDTO, SendDataEcsTaskDefinitionListWebSocketResponseEventDTO, SendDataEcsTasksListWebSocketResponseEventDTO, SendDataRunCommandWebSocketResponseEventDTO, SendDataSsmSessionsListWebSocketResponseEventDTO, SendDataWebSocketResponseEventDTO, SubmissionRunStatusWebSocketResponseEventDTO, SubmissionsCrawlWebSocketResponseEventDTO, SubscribeClientTrackDataWebSocketEventDTO, SubscribeClientTrackWebSocketEventDTO, SubscribeCodeRunStatusWebSocketEventDTO, SubscribeContestChangesWebSocketEventDTO, SubscribeGetDataWebSocketEventDTO, SubscribeProblemCrawledWebSocketEventDTO, SubscribeSubmissionRunStatusWebSocketEventDTO, SubscribeSubmissionsCrawlWebSocketEventDTO, SubscribeUserNotificationWebsocketEventDTO, UnsubscribeClientTrackDataWebSocketEventDTO, UnsubscribeClientTrackWebSocketEventDTO, UnsubscribeCodeRunStatusWebSocketEventDTO, UnsubscribeContestChangesWebSocketEventDTO, UnsubscribeGetDataWebSocketEventDTO, UnsubscribeProblemCrawledWebSocketEventDTO, UnsubscribeSubmissionRunStatusWebSocketEventDTO, UnsubscribeSubmissionsCrawlWebSocketEventDTO, UnsubscribeUserNotificationWebSocketEventDTO, UserMessageWebSocketResponseEventDTO, UserNotificationContestClarificationWebSocketResponseEventDTO, UserNotificationSubmissionWebSocketResponseEventDTO, UserNotificationWebSocketResponseEventDTO, WebSocketChannelsMessageDTO, WebSocketMessageEventDTO, WebSocketResponseEventDTO, WebSocketSubscribeEventDTO, WebSocketUnsubscribeEventDTO } from '../dto';
 import { ClientId, WebSocketResponseEvent, WebSocketResponseEventKey } from '../types';
 export declare const isWebsocketSubscription: (event: any) => event is WebSocketSubscribeEventDTO | WebSocketUnsubscribeEventDTO | WebSocketMessageEventDTO;
 export declare const isPingWebSocketEventDTO: (event: any) => event is PingWebSocketEventDTO;
@@ -22,6 +22,8 @@ export declare const isSubscribeClientTrackWebSocketEventDTO: (event: any) => ev
 export declare const isUnsubscribeClientTrackWebSocketEventDTO: (event: any) => event is UnsubscribeClientTrackWebSocketEventDTO;
 export declare const isSubscribeUserNotificationWebSocketEventDTO: (event: any) => event is SubscribeUserNotificationWebsocketEventDTO;
 export declare const isUnsubscribeUserNotificationWebSocketEventDTO: (event: any) => event is UnsubscribeUserNotificationWebSocketEventDTO;
+export declare const isSubscribeClientTrackDataWebSocketEventDTO: (event: any) => event is SubscribeClientTrackDataWebSocketEventDTO;
+export declare const isUnsubscribeClientTrackDataWebSocketEventDTO: (event: any) => event is UnsubscribeClientTrackDataWebSocketEventDTO;
 export declare const isWebSocketResponseEventDTO: (event: any) => event is WebSocketResponseEventDTO;
 export declare const isPongWebSocketResponseEventDTO: (event: any) => event is PongWebSocketResponseEventDTO;
 export declare const isCodeRunStatusMessageWebSocketResponseEventDTO: (event: any) => event is CodeRunStatusWebSocketResponseEventDTO;
@@ -43,3 +45,20 @@ export declare const isUserNotificationWebSocketResponseEventDTO: (event: any) =
 export declare const isUserNotificationSubmissionWebSocketResponseEventDTO: (event: any) => event is UserNotificationSubmissionWebSocketResponseEventDTO;
 export declare const isUserNotificationContestClarificationWebSocketResponseEventDTO: (event: any) => event is UserNotificationContestClarificationWebSocketResponseEventDTO;
 export declare const getWebSocketResponseEventKey: (event: WebSocketResponseEvent, clientId: ClientId, id: string) => WebSocketResponseEventKey;
+export declare const isWebSocketChannelsMessageDTO: (message: any) => message is WebSocketChannelsMessageDTO;
+/**
+ * Key used by the client to dispatch a response received on a TOPIC channel to its subscribers.
+ * It is the same key that `getKeyWebSocketEventDTO` (base-ui) computes for the subscription.
+ * Returns null when the response is not addressed to this client.
+ */
+export declare const getWebSocketResponseEventKeyOfResponse: (response: WebSocketResponseEventDTO, clientId: ClientId) => WebSocketResponseEventKey | null;
+/**
+ * TOPIC channel that the client has to attach to receive the events of a subscription,
+ * or null when the events arrive by the private channels (session / user) the client is always attached to.
+ * Ably rejects the attach if the token has no capability for the channel.
+ */
+export declare const getChannelOfWebSocketSubscribeEvent: (event: WebSocketSubscribeEventDTO) => string | null;
+/**
+ * Contest whose role channels the client needs (the API grants them when the token is requested with this contest).
+ */
+export declare const getContestKeyOfWebSocketSubscribeEvent: (event: WebSocketSubscribeEventDTO) => string | null;

package/dist/types/types/socket.d.ts

@@ -6,6 +6,10 @@ export declare enum WebSocketMessageEvent {
     CLIENT_TRACK_DEVICE = "CLIENT_TRACK_DEVICE",
     CHAT_COMPLETIONS = "CHAT_COMPLETIONS"
 }
+/**
+ * Subscriptions of the client. With the TOPIC channels they are not sent to the server anymore:
+ * they only say which channel the client attaches (`getChannelOfWebSocketSubscribeEvent`) and the dispatch key.
+ */
 export declare enum WebSocketSubscriptionEvent {
     SUBSCRIBE_CODE_RUN_STATUS = "SUBSCRIBE_CODE_RUN_STATUS",
     UNSUBSCRIBE_CODE_RUN_STATUS = "UNSUBSCRIBE_CODE_RUN_STATUS",
@@ -22,7 +26,9 @@ export declare enum WebSocketSubscriptionEvent {
     SUBSCRIBE_CLIENT_TRACK = "SUBSCRIBE_CLIENT_TRACK",
     UNSUBSCRIBE_CLIENT_TRACK = "UNSUBSCRIBE_CLIENT_TRACK",
     SUBSCRIBE_USER_NOTIFICATION = "SUBSCRIBE_USER_NOTIFICATION",
-    UNSUBSCRIBE_USER_NOTIFICATION = "UNSUBSCRIBE_USER_NOTIFICATION"
+    UNSUBSCRIBE_USER_NOTIFICATION = "UNSUBSCRIBE_USER_NOTIFICATION",
+    SUBSCRIBE_CLIENT_TRACK_DATA = "SUBSCRIBE_CLIENT_TRACK_DATA",
+    UNSUBSCRIBE_CLIENT_TRACK_DATA = "UNSUBSCRIBE_CLIENT_TRACK_DATA"
 }
 export declare enum WebSocketResponseEvent {
     PONG = "PONG",
@@ -47,3 +53,16 @@ export declare enum WebSocketResponseEvent {
 }
 export type ClientId = `${RecordId}|${string}`;
 export type WebSocketResponseEventKey = `${WebSocketResponseEvent}-${ClientId}-${string}`;
+/**
+ * Roles of a contest, with the same names as the contest members in the DB.
+ * Each role has its own Ably channel: `contest:{contestKey}:{role}` (see `CHANNEL_CONTEST`).
+ * The inclusions follow `getContestAccessPermissions`:
+ *   spectators ⊇ managers ⊇ administrators, spectators ⊇ participants, spectators ⊇ guests
+ */
+export declare enum ContestChannelRole {
+    ADMINISTRATORS = "administrators",
+    MANAGERS = "managers",
+    PARTICIPANTS = "participants",
+    GUESTS = "guests",
+    SPECTATORS = "spectators"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juki-team/commons",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "author": "juki-team",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,7 @@
     "rollup": "^4.57.1",
     "rollup-plugin-typescript2": "^0.36.0",
     "typedoc": "^0.28.16",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.3"
   },
   "dependencies": {
     "uuid": "^13.0.0 || ^14.0.0"
@@ -40,6 +40,6 @@
     "watch": "rollup -cw",
     "build": "rm -rf docs && rm -rf dist && rollup -c && pnpm run docs",
     "push-commit": "f() { git add -A && git commit -m \"${1:-chore}\" && pnpm push; }; f",
-    "push": "f() { npm version patch --no-git-tag-version && pnpm build && pnpm publish --tag release-0.1 --no-git-checks && version=\"v$(node -p \"require('./package.json').version\")\" && git add -A && git commit -m $version && git tag -a $version -m $version && git push origin v0.1.x --follow-tags; }; f"
+    "push": "f() { pnpm version patch --no-git-tag-version --no-git-checks && pnpm build && pnpm publish --tag release-0.1 --no-git-checks && version=\"v$(node -p \"require('./package.json').version\")\" && git add -A && git commit -m $version && git tag -a $version -m $version && git push origin v0.1.x --follow-tags; }; f"
   }
 }