@jskit-ai/workspaces-core 0.2.4 → 0.2.5

package/src/server/workspaceMembers/workspaceMembersService.js

@@ -1,11 +1,14 @@
-import { normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
-import { normalizeLowerText, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { joinOrOpenTransaction } from "@jskit-ai/database-runtime/shared";
+import { normalizeLowerText, normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { encodeInviteTokenHash } from "@jskit-ai/auth-core/shared/inviteTokens";
 import { resolveInviteTokenHash, buildInviteToken, hashInviteToken } from "@jskit-ai/auth-core/server/inviteTokens";
+import { returnJsonApiData } from "@jskit-ai/http-runtime/shared";
 import { AppError, createValidationError } from "@jskit-ai/kernel/server/runtime/errors";
-import { OWNER_ROLE_ID, createWorkspaceRoleCatalog, cloneWorkspaceRoleCatalog } from "../../shared/roles.js";
-import { createWorkspacesServerI18n } from "../i18n.js";
-import { renderDefaultWorkspaceInviteEmail } from "./defaultWorkspaceInviteEmail.js";
+import { OWNER_ROLE_ID, cloneWorkspaceRoleCatalog } from "../../shared/roles.js";
+import {
+  buildMailerUnconfiguredDelivery,
+  unconfiguredWorkspaceInviteMailer
+} from "./unconfiguredWorkspaceInviteMailer.js";
 
 const DEFAULT_LOCALE = "en";
 
@@ -15,60 +18,65 @@ function roleNotAssignableError() {
   });
 }
 
+function memberUserIdRequiredError() {
+  return createValidationError({
+    memberUserId: { code: "workspaces.member.userIdRequired", message: "Member user id is required." }
+  });
+}
+
+function inviteIdRequiredError() {
+  return createValidationError({
+    inviteId: { code: "workspaces.invite.idRequired", message: "Invite id is required." }
+  });
+}
+
+/**
+ * @param {object} dependencies
+ * @param {import("../types.js").WorkspaceMembershipsRepository} dependencies.workspaceMembershipsRepository
+ * @param {import("../types.js").WorkspaceInvitesRepository} dependencies.workspaceInvitesRepository
+ * @param {number} dependencies.inviteExpiresInMs
+ * @param {import("../types.js").WorkspaceRoleCatalog} dependencies.roleCatalog
+ * @param {boolean} dependencies.workspaceInvitationsEnabled
+ * @param {import("../types.js").WorkspaceInviteUrlBuilder} dependencies.inviteUrlBuilder
+ * @param {import("../types.js").WorkspaceInviteMailer} dependencies.workspaceInviteMailer
+ *   The provided `workspaces.invite-mailer`, or unconfiguredWorkspaceInviteMailer when no feature provides one.
+ * @param {import("../types.js").WorkspaceInviteEmailTemplate} dependencies.workspaceInviteEmailTemplate
+ * @param {import("../types.js").WorkspacesServerI18n} dependencies.i18n
+ * @param {import("@jskit-ai/users-core/server/types").UserProfilesRepository} dependencies.userProfilesRepository
+ * @param {import("@jskit-ai/users-core/server/types").UserSettingsRepository} dependencies.userSettingsRepository
+ */
 function createService({
   workspaceMembershipsRepository,
   workspaceInvitesRepository,
   inviteExpiresInMs,
-  roleCatalog = null,
-  workspaceInvitationsEnabled = true,
-  inviteUrlBuilder = null,
-  workspaceInviteMailer = null,
-  workspaceInviteEmailTemplate = renderDefaultWorkspaceInviteEmail,
-  i18n = createWorkspacesServerI18n(),
-  userProfilesRepository = null,
-  userSettingsRepository = null
-} = {}) {
-  if (!workspaceMembershipsRepository || !workspaceInvitesRepository) {
-    throw new Error("workspaceMembersService requires membership and invite repositories.");
-  }
-  const resolvedInviteExpiresInMs = Number(inviteExpiresInMs);
-  if (!Number.isInteger(resolvedInviteExpiresInMs) || resolvedInviteExpiresInMs < 1) {
-    throw new Error("workspaceMembersService requires inviteExpiresInMs.");
-  }
-
-  const resolvedRoleCatalog = roleCatalog && typeof roleCatalog === "object" ? roleCatalog : createWorkspaceRoleCatalog();
-  const assignableRoleIds = Array.isArray(resolvedRoleCatalog.assignableRoleIds)
-    ? [...resolvedRoleCatalog.assignableRoleIds]
-    : [];
-  const resolvedWorkspaceInvitationsEnabled = workspaceInvitationsEnabled === true;
-  const resolvedInviteUrlBuilder = typeof inviteUrlBuilder === "function"
-    ? inviteUrlBuilder
-    : ({ token }) => `/invite/${encodeURIComponent(String(token || "").trim())}`;
-  const resolvedWorkspaceInviteMailer =
-    workspaceInviteMailer && typeof workspaceInviteMailer === "object" ? workspaceInviteMailer : null;
-  const resolvedWorkspaceInviteEmailTemplate =
-    typeof workspaceInviteEmailTemplate === "function"
-      ? workspaceInviteEmailTemplate
-      : renderDefaultWorkspaceInviteEmail;
+  roleCatalog,
+  workspaceInvitationsEnabled,
+  inviteUrlBuilder,
+  workspaceInviteMailer,
+  workspaceInviteEmailTemplate,
+  i18n,
+  userProfilesRepository,
+  userSettingsRepository
+}) {
+  const { assignableRoleIds } = roleCatalog;
+  const inviteMailerProvided = workspaceInviteMailer !== unconfiguredWorkspaceInviteMailer;
 
   function ensureWorkspaceInvitationsEnabled() {
-    if (resolvedWorkspaceInvitationsEnabled) {
+    if (workspaceInvitationsEnabled) {
       return;
     }
     throw new AppError(403, "Workspace invitations are disabled.", { code: "workspaces.invite.disabled" });
   }
 
-  function withRoleCatalog(payload = {}) {
+  function withRoleCatalog(payload) {
     return {
       ...payload,
-      roleCatalog: cloneWorkspaceRoleCatalog({
-        ...resolvedRoleCatalog,
-        assignableRoleIds
-      })
+      roleCatalog: cloneWorkspaceRoleCatalog(roleCatalog)
     };
   }
 
-  function mapWorkspaceSummary(workspace = {}) {
+  // The workspace as the members, invites and invitation email show it.
+  function mapMembersWorkspace(workspace) {
     return {
       id: normalizeRecordId(workspace.id, { fallback: "" }),
       slug: normalizeText(workspace.slug),
@@ -78,7 +86,7 @@ function createService({
     };
   }
 
-  function mapMemberSummary(member = {}, workspace = {}) {
+  function mapMemberSummary(member, workspace) {
     const userId = normalizeRecordId(member.userId, { fallback: "" });
     const roleSid = normalizeLowerText(member.roleSid || "member") || "member";
 
@@ -92,7 +100,7 @@ function createService({
     };
   }
 
-  function mapInviteSummary(invite = {}) {
+  function mapInviteSummary(invite) {
     return {
       id: normalizeRecordId(invite.id, { fallback: "" }),
       email: normalizeLowerText(invite.email),
@@ -103,11 +111,19 @@ function createService({
     };
   }
 
-  function normalizeInviteDeliveryResult(value = {}) {
+  /**
+   * A mailer's delivery outcome; the status defaults to "sent".
+   * @param {unknown} value
+   */
+  function normalizeInviteDeliveryResult(value) {
+    /** @type {{ status?: string, message?: string, messageCode?: string, messageParams?: object, providerMessageId?: string }} */
     const source = value && typeof value === "object" && !Array.isArray(value) ? value : {};
     return {
       status: normalizeLowerText(source.status || "sent") || "sent",
       message: normalizeText(source.message),
+      ...(source.messageCode
+        ? { messageCode: normalizeText(source.messageCode), messageParams: { ...source.messageParams } }
+        : {}),
       providerMessageId: normalizeText(source.providerMessageId)
     };
   }
@@ -115,10 +131,6 @@ function createService({
   // The saved locale of an existing account with the invited email, else English.
   // A failed lookup must not stop the invitation, so it also falls back to English.
   async function resolveRecipientLocale(email, options = {}) {
-    if (typeof userProfilesRepository?.findByEmail !== "function" ||
-      typeof userSettingsRepository?.findByUserId !== "function") {
-      return DEFAULT_LOCALE;
-    }
     try {
       const profile = await userProfilesRepository.findByEmail(email, options);
       const settings = profile?.id ? await userSettingsRepository.findByUserId(profile.id, options) : null;
@@ -128,24 +140,19 @@ function createService({
     }
   }
 
-  async function deliverInviteEmail({ workspace, user, invite, inviteUrl } = {}, options = {}) {
-    if (!resolvedWorkspaceInviteMailer || typeof resolvedWorkspaceInviteMailer.sendWorkspaceInvite !== "function") {
-      return {
-        status: "mailer_unconfigured",
-        message: "No workspace invite mailer is configured.",
-        messageCode: "workspaces.invite.mailerUnconfigured",
-        messageParams: {},
-        providerMessageId: ""
-      };
+  async function deliverInviteEmail({ workspace, user, invite, inviteUrl }, options) {
+    // With no mailer provided there is nothing to send, so the recipient's
+    // locale is not looked up and no email is rendered.
+    if (!inviteMailerProvided) {
+      return buildMailerUnconfiguredDelivery();
     }
-
     try {
-      const roleLabel = resolvedRoleCatalog.roles?.find((role) => role.id === invite.roleSid)?.label;
+      const roleLabel = roleCatalog.roles.find((role) => role.id === invite.roleSid)?.label;
       const locale = await resolveRecipientLocale(invite.email, options);
-      const message = await resolvedWorkspaceInviteEmailTemplate({
+      const message = await workspaceInviteEmailTemplate({
         email: invite.email,
         inviteUrl,
-        workspace: mapWorkspaceSummary(workspace),
+        workspace: mapMembersWorkspace(workspace),
         inviter: user || null,
         roleSid: invite.roleSid,
         ...(roleLabel ? { roleLabel } : {}),
@@ -153,17 +160,17 @@ function createService({
         locale,
         t: (key, params) => i18n.t(locale, key, params)
       });
-      const result = await resolvedWorkspaceInviteMailer.sendWorkspaceInvite({
+      const result = await workspaceInviteMailer.sendWorkspaceInvite({
         email: invite.email,
         inviteUrl,
-        workspace: mapWorkspaceSummary(workspace),
+        workspace: mapMembersWorkspace(workspace),
         inviter: user || null,
         roleSid: invite.roleSid,
         expiresAt: invite.expiresAt,
         locale,
         message
       }, options);
-      return normalizeInviteDeliveryResult(result || { status: "sent" });
+      return normalizeInviteDeliveryResult(result);
     } catch {
       return {
         status: "failed",
@@ -176,31 +183,34 @@ function createService({
     }
   }
 
-  async function listRoles(options = {}) {
-    return cloneWorkspaceRoleCatalog({
-      ...resolvedRoleCatalog,
-      assignableRoleIds
-    });
+  // Applications read the role catalog and member list as they are; the
+  // *Response methods answer with them as JSON:API data, for the actions.
+  async function listRoles() {
+    return cloneWorkspaceRoleCatalog(roleCatalog);
   }
 
-  async function listMembersPayload(workspace, options = {}) {
+  async function listRolesResponse() {
+    return returnJsonApiData(await listRoles());
+  }
+
+  async function listMembers(workspace, options = {}) {
     const members = await workspaceMembershipsRepository.listActiveByWorkspaceId(workspace.id, options);
 
     return withRoleCatalog({
-      workspace: mapWorkspaceSummary(workspace),
+      workspace: mapMembersWorkspace(workspace),
       members: members.map((member) => mapMemberSummary(member, workspace))
     });
   }
 
-  async function listMembers(workspace, options = {}) {
-    return listMembersPayload(workspace, options);
+  async function listMembersResponse(workspace, options = {}) {
+    return returnJsonApiData(await listMembers(workspace, options));
   }
 
-  async function updateMemberRole(workspace, payload = {}, options = {}) {
+  async function updateMemberRole(workspace, payload, options = {}) {
     const memberUserId = normalizeRecordId(payload.memberUserId, { fallback: null });
     const roleSid = normalizeLowerText(payload.roleSid || "");
     if (!memberUserId) {
-      throw new AppError(400, "Validation failed.", { code: "validation_failed" });
+      throw memberUserIdRequiredError();
     }
     if (!assignableRoleIds.includes(roleSid)) {
       throw roleNotAssignableError();
@@ -224,13 +234,13 @@ function createService({
       options
     );
 
-    return listMembersPayload(workspace, options);
+    return returnJsonApiData(await listMembers(workspace, options));
   }
 
-  async function removeMember(workspace, payload = {}, options = {}) {
+  async function removeMember(workspace, payload, options = {}) {
     const memberUserId = normalizeRecordId(payload.memberUserId, { fallback: null });
     if (!memberUserId) {
-      throw new AppError(400, "Validation failed.", { code: "validation_failed" });
+      throw memberUserIdRequiredError();
     }
 
     const existingMembership = await workspaceMembershipsRepository.findByWorkspaceIdAndUserId(workspace.id, memberUserId, options);
@@ -251,7 +261,7 @@ function createService({
       options
     );
 
-    return listMembersPayload(workspace, options);
+    return returnJsonApiData(await listMembers(workspace, options));
   }
 
   async function listInvitesPayload(workspace, options = {}) {
@@ -259,17 +269,18 @@ function createService({
     const invites = await workspaceInvitesRepository.listPendingByWorkspaceIdWithWorkspace(workspace.id, options);
 
     return withRoleCatalog({
-      workspace: mapWorkspaceSummary(workspace),
+      workspace: mapMembersWorkspace(workspace),
       invites: invites.map((invite) => mapInviteSummary(invite))
     });
   }
 
-  async function listInvites(workspace, options = {}) {
-    return listInvitesPayload(workspace, options);
+  async function listInvitesResponse(workspace, options = {}) {
+    return returnJsonApiData(await listInvitesPayload(workspace, options));
   }
 
-  async function prepareInvite(workspace, user, payload = {}, options = {}) {
+  async function prepareInvite(workspace, user, payload, options = {}) {
     ensureWorkspaceInvitationsEnabled();
+    // readable-check: allow required-collaborators - platform object: a Knex transaction, which prepareInvite writes in
     if (!options.trx) {
       throw new TypeError("prepareInvite requires a managed transaction.");
     }
@@ -281,7 +292,7 @@ function createService({
 
     const token = buildInviteToken();
     const tokenHash = hashInviteToken(token);
-    const expiresAt = new Date(Date.now() + resolvedInviteExpiresInMs).toISOString();
+    const expiresAt = new Date(Date.now() + inviteExpiresInMs).toISOString();
     await workspaceInvitesRepository.lockWorkspaceForInvitations(workspace.id, options);
     await workspaceInvitesRepository.expirePendingByWorkspaceIdAndEmail(workspace.id, email, options);
     const createdInvite = await workspaceInvitesRepository.insert(
@@ -304,8 +315,9 @@ function createService({
     return { createdInviteId, inviteTokenPreview: token };
   }
 
-  async function sendInvite(workspace, user, prepared = {}, options = {}) {
+  async function sendInvite(workspace, user, prepared, options = {}) {
     ensureWorkspaceInvitationsEnabled();
+    // readable-check: allow required-collaborators - platform object: a Knex transaction, which sendInvite must run after
     if (options.trx) {
       throw new TypeError("sendInvite must run after the invitation transaction commits.");
     }
@@ -335,7 +347,7 @@ function createService({
       name: invite.workspaceName,
       avatarUrl: invite.workspaceAvatarUrl
     };
-    const inviteUrl = resolvedInviteUrlBuilder({ token, invite, workspace: savedWorkspace });
+    const inviteUrl = inviteUrlBuilder({ token, invite, workspace: savedWorkspace });
     const response = await listInvitesPayload(savedWorkspace, options);
     const inviteDelivery = await deliverInviteEmail({ workspace: savedWorkspace, user, invite, inviteUrl }, options);
     return {
@@ -347,22 +359,23 @@ function createService({
     };
   }
 
-  async function createInvite(workspace, user, payload = {}, options = {}) {
+  async function createInvite(workspace, user, payload, options = {}) {
     ensureWorkspaceInvitationsEnabled();
+    // readable-check: allow required-collaborators - platform object: a Knex transaction, which createInvite opens itself
     if (options.trx) {
       throw new TypeError("Use prepareInvite inside a transaction, then sendInvite after commit.");
     }
     const prepared = await workspaceInvitesRepository.withTransaction((trx) =>
       prepareInvite(workspace, user, payload, { ...options, trx })
     );
-    return sendInvite(workspace, user, prepared, options);
+    return returnJsonApiData(await sendInvite(workspace, user, prepared, options));
   }
 
   async function revokeInvite(workspace, inviteId, options = {}) {
     ensureWorkspaceInvitationsEnabled();
     const normalizedInviteId = normalizeRecordId(inviteId, { fallback: null });
     if (!normalizedInviteId) {
-      throw new AppError(400, "Validation failed.", { code: "validation_failed" });
+      throw inviteIdRequiredError();
     }
 
     const revoke = async (trx) => {
@@ -378,23 +391,23 @@ function createService({
       await workspaceInvitesRepository.revokeById(normalizedInviteId, transactionOptions);
       return normalizeRecordId(invite.id, { fallback: null });
     };
-    const revokedInviteId = options.trx
-      ? await revoke(options.trx)
-      : await workspaceInvitesRepository.withTransaction(revoke);
+    const revokedInviteId = await joinOrOpenTransaction(options, workspaceInvitesRepository.withTransaction, revoke);
 
     const response = await listInvitesPayload(workspace, options);
-    return {
+    return returnJsonApiData({
       ...response,
       revokedInviteId
-    };
+    });
   }
 
   return Object.freeze({
     listRoles,
+    listRolesResponse,
     listMembers,
+    listMembersResponse,
     updateMemberRole,
     removeMember,
-    listInvites,
+    listInvitesResponse,
     createInvite,
     prepareInvite,
     sendInvite,

package/src/server/workspacePendingInvitations/noInviteAcceptanceParticipant.js

@@ -0,0 +1,8 @@
+/**
+ * The `workspaces.invite-acceptance-participant` default when no feature
+ * provides one: accepting an invitation activates the membership only.
+ * @type {import("../types.js").WorkspaceInviteAcceptanceParticipant}
+ */
+async function noInviteAcceptanceParticipant() {}
+
+export { noInviteAcceptanceParticipant };

package/src/server/workspacePendingInvitations/workspacePendingInvitationsActions.js

@@ -2,123 +2,90 @@ import { pendingInvitationsAssistantOutput } from "../../shared/resources/worksp
 import {
   emptyInputValidator
 } from "@jskit-ai/kernel/server/actions/actionContributorHelpers";
-import { returnJsonApiData } from "@jskit-ai/http-runtime/shared";
 import { workspaceMembersResource } from "../../shared/resources/workspaceMembersResource.js";
 import { workspacePendingInvitationsResource } from "../../shared/resources/workspacePendingInvitationsResource.js";
 import { createInviteDecisionEvents } from "../common/support/realtimeServiceEvents.js";
-import { resolveActionUser } from "../common/support/resolveActionUser.js";
+import { resolveActionUser } from "@jskit-ai/users-core/server/resolveActionUser";
 
 const WORKSPACE_INVITE_DECISION_EVENTS = createInviteDecisionEvents();
 
-const workspacePendingInvitationsActionSpecifications = Object.freeze([
-  {
-    id: "workspace.invitation.resolve",
-    version: 1,
-    kind: "query",
-    channels: ["api", "automation", "internal"],
-    surfaces: ["*"],
-    permission: {
-      require: "none"
-    },
-    input: workspacePendingInvitationsResource.operations.resolve.query,
-    output: null,
-    extensions: {
-      assistant: {
-        exclude: "Use the invitation screen; raw invitation tokens must not enter assistant arguments."
-      }
-    },
-    idempotency: "none",
-    async run(workspacePendingInvitationsService, input, context) {
-      return returnJsonApiData(
-        await workspacePendingInvitationsService.resolveInviteByToken(input?.token, {
-          context
-        })
-      );
-    }
-  },
-  {
-    id: "workspace.invitations.pending.list",
-    version: 1,
-    kind: "query",
-    channels: ["api", "automation", "internal"],
-    surfaces: ["*"],
-    permission: {
-      require: "authenticated"
-    },
-    input: emptyInputValidator,
-    output: null,
-    extensions: {
-      assistant: {
-        description: "List pending workspace invitations for the signed-in user without invitation tokens.",
-        output: pendingInvitationsAssistantOutput,
-        transformResult: (result) => ({
-          pendingInvites: result.value.pendingInvites.map(
-            ({ id, workspaceId, workspaceSlug, workspaceName, roleSid, status, expiresAt }) =>
-              ({ id, workspaceId, workspaceSlug, workspaceName, roleSid, status, expiresAt })
-          )
-        })
-      }
-    },
-    idempotency: "none",
-    async run(workspacePendingInvitationsService, input, context) {
-      return returnJsonApiData({
-        pendingInvites: await workspacePendingInvitationsService.listPendingInvitesForUser(resolveActionUser(context, input), {
-          context
-        })
-      });
-    }
-  },
-  {
-    id: "workspace.invite.redeem",
-    version: 1,
-    kind: "command",
-    channels: ["api", "automation", "internal"],
-    surfaces: ["*"],
-    permission: {
-      require: "authenticated"
-    },
-    input: workspaceMembersResource.operations.redeemInvite.body,
-    output: null,
-    extensions: {
-      assistant: {
-        exclude: "Use the authenticated invitation screen to accept or refuse; raw invitation tokens must not enter assistant arguments."
-      }
-    },
-    idempotency: "optional",
-    events: WORKSPACE_INVITE_DECISION_EVENTS,
-    async run(workspacePendingInvitationsService, input, context) {
-      const payload = input || {};
-      const user = resolveActionUser(context);
-
-      if (payload.decision === "accept") {
-        return returnJsonApiData(await workspacePendingInvitationsService.acceptInviteByToken({
-          user,
-          token: payload.token
-        }, {
-          context
-        }));
-      }
-
-      return returnJsonApiData(await workspacePendingInvitationsService.refuseInviteByToken({
-        user,
-        token: payload.token
-      }, {
-        context
-      }));
-    }
-  }
-]);
-
-function buildWorkspacePendingInvitationsActions({ workspacePendingInvitationsService } = {}) {
-  if (!workspacePendingInvitationsService) {
-    throw new TypeError("buildWorkspacePendingInvitationsActions requires workspacePendingInvitationsService.");
-  }
-  return workspacePendingInvitationsActionSpecifications.map(({ run, ...definition }) => Object.freeze({
-    ...definition,
-    execute(input, context) {
-      return run(workspacePendingInvitationsService, input, context);
-    }
-  }));
+/** @param {{ workspacePendingInvitationsService: import("../types.js").WorkspacePendingInvitationsService }} dependencies */
+function createWorkspacePendingInvitationsActions({ workspacePendingInvitationsService }) {
+  return Object.freeze([
+    Object.freeze({
+      id: "workspace.invitation.resolve",
+      version: 1,
+      kind: "query",
+      channels: ["api", "automation", "internal"],
+      surfaces: ["*"],
+      permission: {
+        require: "none"
+      },
+      input: { schema: workspacePendingInvitationsResource.operations.resolve.query.schema },
+      output: null,
+      extensions: {
+        assistant: {
+          exclude: "Use the invitation screen; raw invitation tokens must not enter assistant arguments."
+        }
+      },
+      execute: (input, context) => workspacePendingInvitationsService.resolveInviteByToken(
+        input.token,
+        { context }
+      )
+    }),
+    Object.freeze({
+      id: "workspace.invitations.pending.list",
+      version: 1,
+      kind: "query",
+      channels: ["api", "automation", "internal"],
+      surfaces: ["*"],
+      permission: {
+        require: "authenticated"
+      },
+      input: emptyInputValidator,
+      output: null,
+      extensions: {
+        assistant: {
+          description: "List pending workspace invitations for the signed-in user without invitation tokens.",
+          output: pendingInvitationsAssistantOutput,
+          transformResult: (result) => ({
+            pendingInvites: result.value.pendingInvites.map(
+              ({ id, workspaceId, workspaceSlug, workspaceName, roleSid, status, expiresAt }) =>
+                ({ id, workspaceId, workspaceSlug, workspaceName, roleSid, status, expiresAt })
+            )
+          })
+        }
+      },
+      execute: (input, context) => workspacePendingInvitationsService.listPendingInvitesResponse(
+        resolveActionUser(context, input),
+        { context }
+      )
+    }),
+    Object.freeze({
+      id: "workspace.invite.redeem",
+      version: 1,
+      kind: "command",
+      channels: ["api", "automation", "internal"],
+      surfaces: ["*"],
+      permission: {
+        require: "authenticated"
+      },
+      input: workspaceMembersResource.operations.redeemInvite.body,
+      output: null,
+      extensions: {
+        assistant: {
+          exclude: "Use the authenticated invitation screen to accept or refuse; raw invitation tokens must not enter assistant arguments."
+        }
+      },
+      events: WORKSPACE_INVITE_DECISION_EVENTS,
+      // The signed-in actor decides; a user named in the input never stands in for them.
+      execute: (input, context) => workspacePendingInvitationsService.redeemInviteByToken(
+        resolveActionUser(context),
+        input,
+        { context }
+      )
+    })
+  ]);
 }
 
-export { workspacePendingInvitationsActionSpecifications, buildWorkspacePendingInvitationsActions };
+export { createWorkspacePendingInvitationsActions };

package/src/server/workspacePendingInvitations/{bootWorkspacePendingInvitations.js → workspacePendingInvitationsRoutes.js}

@@ -1,4 +1,5 @@
 import { createJsonApiResourceRouteContract } from "@jskit-ai/http-runtime/shared/validators/jsonApiRouteTransport";
+import { resolveActorId } from "@jskit-ai/kernel/server/actions/actionContributorHelpers";
 import { workspaceMembersResource } from "../../shared/resources/workspaceMembersResource.js";
 import { workspacePendingInvitationsResource } from "../../shared/resources/workspacePendingInvitationsResource.js";
 import {
@@ -7,16 +8,21 @@ import {
   WORKSPACE_PENDING_INVITATIONS_TRANSPORT
 } from "../../shared/jsonApiTransports.js";
 
-function resolveAuthenticatedUserRecordId(_record, context = {}) {
-  const userId = context?.request?.user?.id;
-  if (userId != null && String(userId).trim()) {
+/**
+ * The JSON:API record id of a signed-in user's invitations: the user's id.
+ * @param {unknown} _record
+ * @param {{ request: object }} context The route transport's context.
+ */
+function resolveAuthenticatedUserRecordId(_record, context) {
+  const userId = resolveActorId(null, context.request);
+  if (userId) {
     return userId;
   }
 
   throw new Error("JSON:API response requires request.user.id.");
 }
 
-function resolveInviteResolutionRecordId(record = {}) {
+function resolveInviteResolutionRecordId(record) {
   const recordId = record?.id || record?.token;
   if (recordId != null && String(recordId).trim()) {
     return recordId;
@@ -24,11 +30,8 @@ function resolveInviteResolutionRecordId(record = {}) {
   return "workspace-invitation";
 }
 
+/** @param {import("@jskit-ai/kernel/server/types").RuntimeRouter} router */
 function registerWorkspacePendingInvitationsRoutes(router) {
-  if (!router || typeof router.register !== "function") {
-    throw new TypeError("registerWorkspacePendingInvitationsRoutes requires router.register().");
-  }
-
   router.register(
     "GET",
     "/api/workspace/invitations/resolve",