@jskit-ai/workspaces-core 0.2.3 → 0.2.5

package/locales/en.json

@@ -8,9 +8,7 @@
         "invalidPayload": "Invalid authenticated user payload."
       },
       "workspace": {
-        "slugUnavailable": "Unable to generate unique workspace slug.",
         "creationDisabled": "Workspace creation is disabled for this tenancy mode.",
-        "nameRequired": "Workspace name is required.",
         "contextDisabled": "Workspace context is disabled.",
         "slugRequired": "workspaceSlug is required.",
         "notFound": "Workspace not found.",
@@ -18,6 +16,7 @@
       },
       "member": {
         "roleNotAssignable": "Role is not assignable.",
+        "userIdRequired": "Member user id is required.",
         "notFound": "Member not found.",
         "ownerRoleLocked": "Cannot change workspace owner role.",
         "ownerNotRemovable": "Cannot remove workspace owner."
@@ -25,6 +24,7 @@
       "invite": {
         "disabled": "Workspace invitations are disabled.",
         "notFound": "Invite not found.",
+        "idRequired": "Invite id is required.",
         "notFoundOrHandled": "Invite not found or already handled.",
         "invitationNotFoundOrHandled": "Invitation not found or already handled.",
         "workspaceMissing": "Invitation workspace no longer exists.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/workspaces-core",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"
@@ -10,6 +10,9 @@
     "./server/WorkspacesIntegrationsProvider": "./src/server/WorkspacesIntegrationsProvider.js",
     "./server/validators/routeParamsValidator": "./src/server/common/validators/routeParamsValidator.js",
     "./server/support/workspaceRouteInput": "./src/server/support/workspaceRouteInput.js",
+    "./server/support/workspaceCrud": "./src/server/support/workspaceCrud.js",
+    "./server/support/workspaceRoutePaths": "./src/server/support/workspaceRoutePaths.js",
+    "./server/types": "./src/server/types.js",
     "./shared/jsonApiTransports": "./src/shared/jsonApiTransports.js",
     "./shared/settings": "./src/shared/settings.js",
     "./shared/tenancyProfile": "./src/shared/tenancyProfile.js",
@@ -19,11 +22,11 @@
     "./locales/en.json": "./locales/en.json"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime": "0.1.251",
-    "@jskit-ai/json-rest-api-core": "0.2.2",
-    "@jskit-ai/resource-core": "0.1.193",
-    "@jskit-ai/resource-crud-core": "0.1.193",
-    "@jskit-ai/users-core": "0.2.3",
+    "@jskit-ai/database-runtime": "0.1.253",
+    "@jskit-ai/json-rest-api-core": "0.2.4",
+    "@jskit-ai/resource-core": "0.1.195",
+    "@jskit-ai/resource-crud-core": "0.1.195",
+    "@jskit-ai/users-core": "0.2.5",
     "json-rest-schema": "^1.0.17"
   },
   "description": "Workspace tenancy runtime plus HTTP routes, role catalog, and workspace config scaffolding.",
@@ -86,8 +89,32 @@
       "apiSummary": {
         "surfaces": [
           {
-            "subpath": "./server",
-            "summary": "Exports the explicit workspace feature, integrations, services, repositories, actions, and routes."
+            "subpath": "./server/WorkspacesFeature",
+            "summary": "Exports WorkspacesFeature, which provides workspaces.core (directory, members, pending invitations and settings services, their actions and routes), and the optional tokens' defaults."
+          },
+          {
+            "subpath": "./server/WorkspacesIntegrationsProvider",
+            "summary": "Exports WorkspacesIntegrationsProvider, which adds workspace context, visibility, provisioning, realtime audiences and invitation context to auth, users and actions."
+          },
+          {
+            "subpath": "./server/validators/routeParamsValidator",
+            "summary": "Exports the workspaceSlug route params validator."
+          },
+          {
+            "subpath": "./server/support/workspaceRouteInput",
+            "summary": "Exports the action input a workspace route's params give, and requestedWorkspaceScope, the workspace a request asks for before the workspace context exists."
+          },
+          {
+            "subpath": "./server/support/workspaceCrud",
+            "summary": "Exports WORKSPACE_CRUD_SCOPE, the workspace scope of CRUD resources."
+          },
+          {
+            "subpath": "./server/support/workspaceRoutePaths",
+            "summary": "Exports the workspace route base path and resolveWorkspaceRoutePath."
+          },
+          {
+            "subpath": "./server/types",
+            "summary": "Type of the workspaces.core capability, for features that require it."
           }
         ],
         "capabilities": [
@@ -171,8 +198,8 @@
     }
   },
   "peerDependencies": {
-    "@jskit-ai/auth-core": "0.2.2",
-    "@jskit-ai/http-runtime": "0.2.2",
-    "@jskit-ai/kernel": "0.2.2"
+    "@jskit-ai/auth-core": "0.2.4",
+    "@jskit-ai/http-runtime": "0.2.4",
+    "@jskit-ai/kernel": "0.2.4"
   }
 }

package/patterns/workspace-server/PATTERN.md

@@ -24,8 +24,8 @@ Choose workspace creation policy, roles, invitation policy, expiry, email copy,
 member permissions, personal-workspace behavior, and surface access rules.
 
 In `workspaces` mode, `tenancyPolicy.workspace.autoProvision: true` gives every
-user a personal workspace in addition to shared ones; the server config function
-`personalWorkspaceName(user)` names it. `workspaceSettings.defaults` sets
+user a personal workspace in addition to shared ones; the optional
+`workspaces.personal-workspace-name` capability, a function of the user, names it. `workspaceSettings.defaults` sets
 `invitesEnabled` and the colours (`lightPrimaryColor`, `darkPrimaryColor` and
 the other palette fields) that new workspaces start with.
 
@@ -63,16 +63,16 @@ catalogue entries. Updating labels requires no database migration.
 
 ## Transactional invitation participation
 
-Through `workspaces.core`, register one callback during feature setup with
-`workspaces.services.pendingInvitations.registerAcceptanceParticipant(fn)`.
-The built-in `workspace.invite.redeem` action invokes
-`fn({ invite, user }, { trx, context })` after validating the recipient, state and
-expiry and activating membership in the uncommitted transaction. Forward `trx`
-to every application owner and propagate failures. JSKIT marks accepted and
-commits after the callback succeeds. Keep external effects out of the callback.
-Registration rejects non-functions, duplicates and calls after acceptance/refusal
-begins. Allow ordinary invitations; reject stale, revoked, conflicting or
-unexpectedly missing application associations.
+Provide one function as the optional `workspaces.invite-acceptance-participant`
+capability, from a small application feature that requires only what its writes
+need (it cannot require `workspaces.core`, which receives it). The built-in
+`workspace.invite.redeem` action invokes `fn({ invite, user }, { trx, context })`
+after validating the recipient, state and expiry and activating membership in the
+uncommitted transaction. Forward `trx` to every application owner and propagate
+failures. JSKIT marks accepted and commits after the function succeeds. Keep
+external effects out of it. Without the capability, acceptance activates the
+membership only. Allow ordinary invitations; reject stale, revoked, conflicting
+or unexpectedly missing application associations.
 
 Use `members.prepareInvite(workspace, actor,
 payload, { trx, context })` in `repositories.workspaceInvites.withTransaction`
@@ -91,8 +91,8 @@ exception, or the normalized mailer result. Persistence is unchanged by delivery
 failure. A provider may accept a message before failing; the application owns
 receipts and retries. Keep tokens/URLs out of logs and use controlled mailers in tests.
 
-`createInvite`, acceptance and refusal now own managed transactions and reject
-borrowed `options.trx`. Use preparation followed by delivery after commit for
+`createInvite`, acceptance and refusal own their managed transactions and
+reject a borrowed `options.trx`. Use preparation followed by delivery after commit for
 transactional creation; put related acceptance writes in the participant. Revocation may join
 a managed transaction. Raw Knex/savepoint transactions cannot own resource
 writes. Invitation mutations lock workspace then invitation rows, revalidate
@@ -115,9 +115,34 @@ authorization, identity/training linking, scope eligibility and required audit.
 
 ## Example files
 
-`example/config/roles.js` is a concrete role catalogue.
-`example/packages/main/src/server/email/workspaceInviteEmail.js` demonstrates an
-app-owned invitation renderer. Compose both through normal application config.
+`example/config/roles.js` is a concrete role catalogue, set as the
+application's `roleCatalog` config.
+
+The invitation email comes from two optional `workspaces.core` capabilities,
+which one small application feature provides:
+`example/packages/main/src/server/WorkspaceInvitationsFeature.js`.
+
+```js
+provides: {
+  inviteEmailTemplate: "workspaces.invite-email-template",
+  inviteMailer: "workspaces.invite-mailer"
+},
+setup({ env }) {
+  return {
+    inviteEmailTemplate: renderWorkspaceInviteEmail,
+    inviteMailer: createWorkspaceInviteMailer({ env })
+  };
+}
+```
+
+- `email/workspaceInviteEmail.js` is the renderer, a
+  `WorkspaceInviteEmailTemplate` returning `{ subject, text, html }`.
+- `email/workspaceInviteMailer.js` is the mailer, a `WorkspaceInviteMailer`
+  whose `sendWorkspaceInvite` sends the rendered message over SMTP.
+
+Without a renderer, workspaces-core uses its built-in email; without a mailer,
+invitations are created and their delivery reports `mailer_unconfigured`. The
+feature must not require `workspaces.core`, which receives both.
 
 ## Variation points
 

package/patterns/workspace-server/example/packages/main/src/server/WorkspaceInvitationsFeature.js

@@ -0,0 +1,27 @@
+import { defineFeature } from "@jskit-ai/kernel/server/features";
+import { renderWorkspaceInviteEmail } from "./email/workspaceInviteEmail.js";
+import { createWorkspaceInviteMailer } from "./email/workspaceInviteMailer.js";
+
+/**
+ * The application's invitation email: the renderer and the mailer that sends
+ * it, each filling one of workspaces-core's optional tokens.
+ */
+const WorkspaceInvitationsFeature = defineFeature({
+  id: "main.workspace-invitations",
+  requires: {
+    env: "runtime.env"
+  },
+  provides: {
+    inviteEmailTemplate: "workspaces.invite-email-template",
+    inviteMailer: "workspaces.invite-mailer"
+  },
+  /** @param {{ env: import("@jskit-ai/kernel/server/types").RuntimeEnv }} capabilities */
+  setup({ env }) {
+    return {
+      inviteEmailTemplate: renderWorkspaceInviteEmail,
+      inviteMailer: createWorkspaceInviteMailer({ env })
+    };
+  }
+});
+
+export { WorkspaceInvitationsFeature };

package/patterns/workspace-server/example/packages/main/src/server/email/workspaceInviteEmail.js

@@ -1,13 +1,14 @@
-function renderWorkspaceInviteEmail({
-  inviteUrl = "",
-  workspace = {},
-  inviter = null,
-  roleSid = "member",
-  expiresAt = ""
-} = {}) {
-  const workspaceName = String(workspace?.name || workspace?.slug || "the workspace").trim() || "the workspace";
-  const inviterName = String(inviter?.displayName || inviter?.email || "").trim();
-  const roleName = String(roleSid || "member").trim() || "member";
+/**
+ * The application's invitation email, provided as
+ * `workspaces.invite-email-template`. workspaces-core passes every field; the
+ * inviter is null when no one is signed in, and `roleLabel` is present only
+ * when the role catalogue names the role.
+ * @type {import("@jskit-ai/workspaces-core/server/types").WorkspaceInviteEmailTemplate}
+ */
+function renderWorkspaceInviteEmail({ inviteUrl, workspace, inviter, roleSid, roleLabel, expiresAt }) {
+  const workspaceName = workspace.name || workspace.slug;
+  const inviterName = inviter?.displayName || inviter?.email || "";
+  const roleName = roleLabel || roleSid;
   const intro = inviterName
     ? `${inviterName} invited you to join ${workspaceName} as ${roleName}.`
     : `You have been invited to join ${workspaceName} as ${roleName}.`;

package/patterns/workspace-server/example/packages/main/src/server/email/workspaceInviteMailer.js

@@ -0,0 +1,27 @@
+import nodemailer from "nodemailer";
+
+/**
+ * The application's `workspaces.invite-mailer`: sends each rendered
+ * invitation through the SMTP server `SMTP_URL` names, from `MAIL_FROM`.
+ * @param {object} dependencies
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} dependencies.env
+ * @returns {import("@jskit-ai/workspaces-core/server/types").WorkspaceInviteMailer}
+ */
+function createWorkspaceInviteMailer({ env }) {
+  const transport = nodemailer.createTransport(env.SMTP_URL);
+
+  async function sendWorkspaceInvite({ email, message }) {
+    const sent = await transport.sendMail({
+      from: env.MAIL_FROM,
+      to: email,
+      subject: message.subject,
+      text: message.text,
+      ...(message.html ? { html: message.html } : {})
+    });
+    return { status: "sent", providerMessageId: sent.messageId };
+  }
+
+  return Object.freeze({ sendWorkspaceInvite });
+}
+
+export { createWorkspaceInviteMailer };

package/src/server/WorkspacesFeature.js

@@ -1,178 +1,18 @@
-import { toDatabaseDateTimeUtc } from "@jskit-ai/database-runtime/shared";
-import {
-  addResourceIfMissing,
-  createJsonRestResourceScopeOptions
-} from "@jskit-ai/json-rest-api-core/server/jsonRestApiHost";
 import { defineFeature } from "@jskit-ai/kernel/server/features";
-import { workspaceInvitesResource } from "../shared/resources/workspaceInvitesResource.js";
-import { workspaceMembershipsResource } from "../shared/resources/workspaceMembershipsResource.js";
-import { workspaceResource } from "../shared/resources/workspaceResource.js";
-import { workspaceSettingsResource } from "../shared/resources/workspaceSettingsResource.js";
-import { createWorkspaceRoleCatalog } from "../shared/roles.js";
-import { WORKSPACE_SETTINGS_COLOR_FIELDS, normalizeWorkspaceHexColor } from "../shared/settings.js";
-import { resolveTenancyProfile } from "../shared/tenancyProfile.js";
-import { createRepository as createWorkspaceInvitesRepository } from "./common/repositories/workspaceInvitesRepository.js";
-import { createRepository as createWorkspaceMembershipsRepository } from "./common/repositories/workspaceMembershipsRepository.js";
-import { createRepository as createWorkspacesRepository } from "./common/repositories/workspacesRepository.js";
-import { createService as createWorkspaceService } from "./common/services/workspaceContextService.js";
-import { createWorkspacesServerI18n } from "./i18n.js";
 import { createWorkspaceBootstrapContributor } from "./workspaceBootstrapContributor.js";
-import { registerWorkspaceDirectoryRoutes } from "./workspaceDirectory/bootWorkspaceDirectoryRoutes.js";
-import { buildWorkspaceDirectoryActions } from "./workspaceDirectory/workspaceDirectoryActions.js";
+import { registerWorkspaceDirectoryRoutes } from "./workspaceDirectory/workspaceDirectoryRoutes.js";
+import { createWorkspaceDirectoryActions } from "./workspaceDirectory/workspaceDirectoryActions.js";
+import { registerWorkspaceMembersRoutes } from "./workspaceMembers/workspaceMembersRoutes.js";
+import { createWorkspaceMembersActions } from "./workspaceMembers/workspaceMembersActions.js";
+import { registerWorkspacePendingInvitationsRoutes } from "./workspacePendingInvitations/workspacePendingInvitationsRoutes.js";
+import { createWorkspacePendingInvitationsActions } from "./workspacePendingInvitations/workspacePendingInvitationsActions.js";
+import { registerWorkspaceSettingsRoutes } from "./workspaceSettings/workspaceSettingsRoutes.js";
+import { unconfiguredWorkspaceInviteMailer } from "./workspaceMembers/unconfiguredWorkspaceInviteMailer.js";
 import { renderDefaultWorkspaceInviteEmail } from "./workspaceMembers/defaultWorkspaceInviteEmail.js";
-import { registerWorkspaceMembersRoutes } from "./workspaceMembers/bootWorkspaceMembers.js";
-import { buildWorkspaceMembersActions } from "./workspaceMembers/workspaceMembersActions.js";
-import { createWorkspaceInviteUrlBuilder } from "./workspaceMembers/workspaceInviteUrls.js";
-import { createService as createWorkspaceMembersService } from "./workspaceMembers/workspaceMembersService.js";
-import { registerWorkspacePendingInvitationsRoutes } from "./workspacePendingInvitations/bootWorkspacePendingInvitations.js";
-import { buildWorkspacePendingInvitationsActions } from "./workspacePendingInvitations/workspacePendingInvitationsActions.js";
-import { createService as createWorkspacePendingInvitationsService } from "./workspacePendingInvitations/workspacePendingInvitationsService.js";
-import { registerWorkspaceSettingsRoutes } from "./workspaceSettings/bootWorkspaceSettings.js";
-import { createRepository as createWorkspaceSettingsRepository } from "./workspaceSettings/workspaceSettingsRepository.js";
-import { buildWorkspaceSettingsActions } from "./workspaceSettings/workspaceSettingsActions.js";
-import { createService as createWorkspaceSettingsService } from "./workspaceSettings/workspaceSettingsService.js";
-import { resolveWorkspaceInvitationsPolicy } from "./support/workspaceInvitationsPolicy.js";
-import { workspaceSlugParamsValidator } from "./common/validators/routeParamsValidator.js";
-import { buildWorkspaceInputFromRouteParams } from "./support/workspaceRouteInput.js";
-import { resolveWorkspace } from "./support/resolveWorkspace.js";
-
-function requirePositiveInteger(value, label) {
-  const normalized = Number(value);
-  if (!Number.isInteger(normalized) || normalized < 1) {
-    throw new TypeError(`${label} must be a positive integer.`);
-  }
-  return normalized;
-}
-
-function requireBoolean(value, label) {
-  if (typeof value !== "boolean") {
-    throw new TypeError(`${label} must be boolean.`);
-  }
-  return value;
-}
-
-function requireWorkspaceColorDefaults(defaults) {
-  const colors = {};
-  for (const fieldName of WORKSPACE_SETTINGS_COLOR_FIELDS) {
-    if (defaults?.[fieldName] === undefined) {
-      continue;
-    }
-    const color = normalizeWorkspaceHexColor(defaults[fieldName]);
-    if (!color) {
-      throw new TypeError(`runtime.config.workspaceSettings.defaults.${fieldName} must be a hex color like #1867C0.`);
-    }
-    colors[fieldName] = color;
-  }
-  return colors;
-}
-
-function resolveInviteEmailTemplate(config) {
-  const template =
-    config.workspaceInviteEmailTemplate ||
-    config.workspaceInviteEmailRenderer ||
-    config.workspaceInvitations?.emailTemplate ||
-    config.workspaceInvitations?.emailRenderer;
-  return typeof template === "function" ? template : renderDefaultWorkspaceInviteEmail;
-}
-
-async function installWorkspaceResources(jsonRestApi) {
-  const scopeOptions = { writeSerializers: { "datetime-utc": toDatabaseDateTimeUtc } };
-  await addResourceIfMissing(
-    jsonRestApi,
-    "workspaces",
-    createJsonRestResourceScopeOptions(workspaceResource, scopeOptions)
-  );
-  await addResourceIfMissing(
-    jsonRestApi,
-    "workspaceMemberships",
-    createJsonRestResourceScopeOptions(workspaceMembershipsResource, scopeOptions)
-  );
-  await addResourceIfMissing(
-    jsonRestApi,
-    "workspaceInvites",
-    createJsonRestResourceScopeOptions(workspaceInvitesResource, scopeOptions)
-  );
-  await addResourceIfMissing(
-    jsonRestApi,
-    "workspaceSettings",
-    createJsonRestResourceScopeOptions(workspaceSettingsResource, scopeOptions)
-  );
-}
-
-function createWorkspacesRuntime({ appRoot = "", config, env, jsonRestApi, users = null } = {}) {
-  const tenancyProfile = resolveTenancyProfile(config);
-  const invitationsPolicy = resolveWorkspaceInvitationsPolicy({ config, appConfig: config, tenancyProfile });
-  const invitationsEnabled = invitationsPolicy.enabled === true;
-  const roleCatalog = createWorkspaceRoleCatalog(config);
-  const workspaceSettingsRepository = createWorkspaceSettingsRepository({
-    api: jsonRestApi,
-    defaultInvitesEnabled: requireBoolean(
-      config?.workspaceSettings?.defaults?.invitesEnabled,
-      "runtime.config.workspaceSettings.defaults.invitesEnabled"
-    ),
-    defaultColorSettings: requireWorkspaceColorDefaults(config?.workspaceSettings?.defaults)
-  });
-  const workspacesRepository = createWorkspacesRepository({ api: jsonRestApi });
-  const workspaceMembershipsRepository = createWorkspaceMembershipsRepository({ api: jsonRestApi });
-  const workspaceInvitesRepository = createWorkspaceInvitesRepository({ api: jsonRestApi });
-  const workspaceService = createWorkspaceService({
-    appConfig: config,
-    workspacesRepository,
-    workspaceMembershipsRepository,
-    workspaceSettingsRepository
-  });
-  const workspacePendingInvitationsService = createWorkspacePendingInvitationsService({
-    workspaceInvitesRepository,
-    workspaceMembershipsRepository,
-    roleCatalog
-  });
-  const workspaceMembersService = createWorkspaceMembersService({
-    workspaceMembershipsRepository,
-    workspaceInvitesRepository,
-    inviteExpiresInMs: requirePositiveInteger(
-      config?.workspaceMembers?.defaults?.inviteExpiresInMs,
-      "runtime.config.workspaceMembers.defaults.inviteExpiresInMs"
-    ),
-    roleCatalog,
-    workspaceInvitationsEnabled: invitationsEnabled,
-    inviteUrlBuilder: createWorkspaceInviteUrlBuilder({ appConfig: config, env }),
-    workspaceInviteMailer: config?.workspaceInviteMailer || null,
-    workspaceInviteEmailTemplate: resolveInviteEmailTemplate(config),
-    i18n: createWorkspacesServerI18n({ appRoot }),
-    userProfilesRepository: users?.repositories?.userProfiles || null,
-    userSettingsRepository: users?.repositories?.userSettings || null
-  });
-  const workspaceSettingsService = createWorkspaceSettingsService({
-    workspaceSettingsRepository,
-    workspaceInvitationsEnabled: invitationsEnabled,
-    roleCatalog
-  });
-
-  return Object.freeze({
-    config,
-    enabled: tenancyProfile.workspace.enabled === true,
-    invitationsEnabled,
-    selfCreateEnabled: tenancyProfile.workspace.allowSelfCreate === true,
-    scope: Object.freeze({
-      params: workspaceSlugParamsValidator,
-      buildInputFromRouteParams: buildWorkspaceInputFromRouteParams,
-      resolveWorkspace
-    }),
-    tenancyProfile,
-    repositories: Object.freeze({
-      workspaceInvites: workspaceInvitesRepository,
-      workspaceMemberships: workspaceMembershipsRepository,
-      workspaceSettings: workspaceSettingsRepository,
-      workspaces: workspacesRepository
-    }),
-    services: Object.freeze({
-      directory: workspaceService,
-      members: workspaceMembersService,
-      pendingInvitations: workspacePendingInvitationsService,
-      settings: workspaceSettingsService
-    })
-  });
-}
+import { noInviteAcceptanceParticipant } from "./workspacePendingInvitations/noInviteAcceptanceParticipant.js";
+import { buildWorkspaceName } from "./common/services/workspaceDirectoryService.js";
+import { createWorkspaceSettingsActions } from "./workspaceSettings/workspaceSettingsActions.js";
+import { createWorkspacesRuntime, installWorkspaceResources } from "./workspacesRuntime.js";
 
 const WorkspacesFeature = defineFeature({
   id: "workspaces.core",
@@ -186,18 +26,59 @@ const WorkspacesFeature = defineFeature({
     jsonRestApi: "runtime.json-rest-api",
     users: "users.core"
   },
+  optional: {
+    inviteAcceptanceParticipant: "workspaces.invite-acceptance-participant",
+    inviteEmailTemplate: "workspaces.invite-email-template",
+    inviteMailer: "workspaces.invite-mailer",
+    personalWorkspaceName: "workspaces.personal-workspace-name"
+  },
   provides: {
     workspaces: "workspaces.core"
   },
-  async setup({ appRoot, bootstrap, config, env, http, jsonRestApi, users }) {
+  /**
+   * @param {object} capabilities
+   * @param {import("@jskit-ai/kernel/server/types").RuntimeAppRoot} capabilities.appRoot
+   * @param {import("@jskit-ai/kernel/server/types").RuntimeBootstrap} capabilities.bootstrap
+   * @param {import("@jskit-ai/kernel/server/types").RuntimeConfig} capabilities.config
+   * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} capabilities.env
+   * @param {import("@jskit-ai/kernel/server/types").RuntimeHttp} capabilities.http
+   * @param {import("./types.js").WorkspaceInviteAcceptanceParticipant | null} capabilities.inviteAcceptanceParticipant
+   * @param {import("./types.js").WorkspaceInviteEmailTemplate | null} capabilities.inviteEmailTemplate
+   * @param {import("./types.js").WorkspaceInviteMailer | null} capabilities.inviteMailer
+   * @param {import("@jskit-ai/json-rest-api-core/server/types").RuntimeJsonRestApi} capabilities.jsonRestApi
+   * @param {import("./types.js").PersonalWorkspaceName | null} capabilities.personalWorkspaceName
+   * @param {import("@jskit-ai/users-core/server/types").UsersCore} capabilities.users
+   */
+  async setup({
+    appRoot,
+    bootstrap,
+    config,
+    env,
+    http,
+    inviteAcceptanceParticipant,
+    inviteEmailTemplate,
+    inviteMailer,
+    jsonRestApi,
+    personalWorkspaceName,
+    users
+  }) {
     await installWorkspaceResources(jsonRestApi);
-    const workspaces = createWorkspacesRuntime({ appRoot, config, env, jsonRestApi, users });
+    const workspaces = createWorkspacesRuntime({
+      appRoot,
+      config,
+      env,
+      inviteAcceptanceParticipant: inviteAcceptanceParticipant ?? noInviteAcceptanceParticipant,
+      inviteEmailTemplate: inviteEmailTemplate ?? renderDefaultWorkspaceInviteEmail,
+      inviteMailer: inviteMailer ?? unconfiguredWorkspaceInviteMailer,
+      jsonRestApi,
+      personalWorkspaceName: personalWorkspaceName ?? buildWorkspaceName,
+      users
+    });
 
     bootstrap.register({
       id: "workspaces.bootstrap",
       order: 200,
       contribute: createWorkspaceBootstrapContributor({
-        appConfig: config,
         tenancyProfile: workspaces.tenancyProfile,
         userProfilesRepository: users.repositories.userProfiles,
         workspaceInvitationsEnabled: workspaces.invitationsEnabled,
@@ -224,18 +105,28 @@ const WorkspacesFeature = defineFeature({
     return { workspaces };
   },
   actions({ workspaces }) {
-    if (!workspaces.enabled) return [];
-    return [
-      ...buildWorkspaceDirectoryActions({ workspaceService: workspaces.services.directory }),
-      ...buildWorkspaceSettingsActions({ workspaceSettingsService: workspaces.services.settings }),
-      ...buildWorkspaceMembersActions({ workspaceMembersService: workspaces.services.members }),
+    if (!workspaces.enabled) return Object.freeze([]);
+    return Object.freeze([
+      ...createWorkspaceDirectoryActions({ workspaceService: workspaces.services.directory }),
+      ...createWorkspaceSettingsActions({ workspaceSettingsService: workspaces.services.settings }),
+      ...createWorkspaceMembersActions({ workspaceMembersService: workspaces.services.members }),
       ...(workspaces.invitationsEnabled
-        ? buildWorkspacePendingInvitationsActions({
+        ? createWorkspacePendingInvitationsActions({
             workspacePendingInvitationsService: workspaces.services.pendingInvitations
           })
         : [])
-    ];
+    ]);
   }
 });
 
-export { WorkspacesFeature, createWorkspacesRuntime, installWorkspaceResources };
+// Applications' tests build the runtime and install its resources directly, from
+// this package's public feature path, with the optional tokens' defaults.
+export {
+  WorkspacesFeature,
+  buildWorkspaceName,
+  createWorkspacesRuntime,
+  installWorkspaceResources,
+  noInviteAcceptanceParticipant,
+  renderDefaultWorkspaceInviteEmail,
+  unconfiguredWorkspaceInviteMailer
+};

package/src/server/WorkspacesIntegrationsProvider.js

@@ -7,8 +7,12 @@ import {
   resolveWorkspaceSurfaceIdsFromAppConfig
 } from "./support/workspaceActionSurfaces.js";
 
-// Every active membership puts the actor in the workspace audience and in its
-// own workspace-user audience.
+/**
+ * Every active membership puts the actor in the workspace audience and in its
+ * own workspace-user audience.
+ * @param {import("./types.js").WorkspaceMembershipsRepository} workspaceMemberships
+ * @param {string} actorId
+ */
 async function resolveWorkspaceRealtimeScopes(workspaceMemberships, actorId) {
   const workspaceIds = await workspaceMemberships.listActiveWorkspaceIdsByUserId(actorId);
   return workspaceIds.flatMap((workspaceId) => [
@@ -30,6 +34,16 @@ const WorkspacesIntegrationsProvider = defineProvider({
   optional: {
     realtime: "runtime.realtime"
   },
+  /**
+   * @param {object} capabilities
+   * @param {import("@jskit-ai/kernel/server/types").ActionCatalogue} capabilities.actions
+   * @param {import("@jskit-ai/auth-core/server/types").AuthExtensions} capabilities.authExtensions
+   * @param {import("@jskit-ai/kernel/server/types").RuntimeConfig} capabilities.config
+   * @param {import("@jskit-ai/kernel/server/types").RuntimeHttp} capabilities.http
+   * @param {import("@jskit-ai/realtime/server/types").RuntimeRealtime | null} capabilities.realtime The installed realtime runtime, when there is one.
+   * @param {import("@jskit-ai/users-core/server/types").UsersExtensions} capabilities.usersExtensions
+   * @param {import("./types.js").WorkspacesCore} capabilities.workspaces
+   */
   setup({ actions, authExtensions, config, http, realtime, usersExtensions, workspaces }) {
     const workspaceService = workspaces.services.directory;
     const membershipOptionalSurfaceIds = resolveWorkspaceMembershipOptionalSurfaceIdsFromAppConfig(config);
@@ -66,18 +80,20 @@ const WorkspacesIntegrationsProvider = defineProvider({
     usersExtensions.registerProfileSyncLifecycleContributor({
       contributorId: "workspaces.provisioning",
       order: 100,
-      async afterIdentityProfileSynced({ profile, options } = {}) {
+      async afterIdentityProfileSynced({ profile, options }) {
         await workspaceService.ensureProvisionedWorkspaceForAuthenticatedUser(profile, options);
       }
     });
 
-    realtime?.registerAudienceContributor({
-      id: "workspaces.memberships",
-      resolveActorScopes: (actorId) => resolveWorkspaceRealtimeScopes(
-        workspaces.repositories.workspaceMemberships,
-        actorId
-      )
-    });
+    if (realtime) {
+      realtime.registerAudienceContributor({
+        id: "workspaces.memberships",
+        resolveActorScopes: (actorId) => resolveWorkspaceRealtimeScopes(
+          workspaces.repositories.workspaceMemberships,
+          actorId
+        )
+      });
+    }
 
     if (workspaces.invitationsEnabled) {
       authExtensions.registerInvitationContextResolver({