@jskit-ai/workspaces-core 0.2.4 → 0.2.6

package/src/server/workspaceDirectory/workspaceDirectoryActions.js

@@ -1,12 +1,8 @@
-import {
-  emptyInputValidator,
-  resolveRequest
-} from "@jskit-ai/kernel/server/actions/actionContributorHelpers";
-import { returnJsonApiData } from "@jskit-ai/http-runtime/shared";
+import { emptyInputValidator } from "@jskit-ai/kernel/server/actions/actionContributorHelpers";
 import { composeSchemaDefinitions } from "@jskit-ai/kernel/shared/validators";
 import { workspaceResource } from "../../shared/resources/workspaceResource.js";
 import { workspaceSlugParamsValidator } from "../common/validators/routeParamsValidator.js";
-import { resolveActionUser } from "../common/support/resolveActionUser.js";
+import { resolveActionUser } from "@jskit-ai/users-core/server/resolveActionUser";
 
 function workspaceAssistantSummary({ id, slug, name, ownerUserId, avatarUrl }) {
   return { id, slug, name, ownerUserId, avatarUrl };
@@ -20,140 +16,112 @@ const workspaceUpdateInputValidator = composeSchemaDefinitions([
   context: "workspaceDirectoryActions.workspaceUpdateInputValidator"
 });
 
-const workspaceDirectoryActionSpecifications = Object.freeze([
-  {
-    id: "workspace.workspaces.create",
-    version: 1,
-    kind: "command",
-    channels: ["api", "assistant_tool", "automation", "internal"],
-    surfaces: ["*"],
-    permission: {
-      require: "authenticated"
-    },
-    input: workspaceResource.operations.create.body,
-    output: null,
-    extensions: {
-      assistant: {
-        description: "Create a workspace for the signed-in user.",
-        output: workspaceResource.operations.create.output,
-        transformResult: (result) => workspaceAssistantSummary(result.value)
-      }
-    },
-    idempotency: "none",
-    async run(workspaceService, input, context) {
-      return returnJsonApiData(await workspaceService.createWorkspaceForAuthenticatedUser(resolveActionUser(context, input), input, {
-        request: resolveRequest(context),
-        context
-      }));
-    }
-  },
-  {
-    id: "workspace.workspaces.list",
-    version: 1,
-    kind: "query",
-    channels: ["api", "automation", "internal"],
-    surfaces: ["*"],
-    permission: {
-      require: "authenticated"
-    },
-    input: emptyInputValidator,
-    output: null,
-    extensions: {
-      assistant: {
-        description: "List workspaces accessible to the signed-in user.",
-        output: workspaceResource.operations.list.output,
-        transformResult: (result) => ({
-          items: result.value.items.map(({ id, slug, name, avatarUrl, roleSid, isAccessible }) =>
-            ({ id, slug, name, avatarUrl, roleSid, isAccessible })),
-          nextCursor: result.value.nextCursor
-        })
-      }
-    },
-    idempotency: "none",
-    async run(workspaceService, input, context) {
-      return returnJsonApiData({
-        items: await workspaceService.listWorkspacesForAuthenticatedUser(resolveActionUser(context, input), {
-          request: resolveRequest(context),
-          context
-        }),
-        nextCursor: null
-      });
-    }
-  },
-  {
-    id: "workspace.workspaces.read",
-    version: 1,
-    kind: "query",
-    channels: ["api", "automation", "internal"],
-    surfaces: ["*"],
-    permission: {
-      require: "any",
-      permissions: ["workspace.settings.view", "workspace.settings.update"]
-    },
-    input: workspaceSlugParamsValidator,
-    output: null,
-    extensions: {
-      assistant: {
-        description: "Read the active workspace profile.",
-        output: workspaceResource.operations.view.output,
-        transformResult: (result) => workspaceAssistantSummary(result.value)
-      }
-    },
-    idempotency: "none",
-    async run(workspaceService, input, context) {
-      return returnJsonApiData(await workspaceService.getWorkspaceForAuthenticatedUser(
+/** @param {{ workspaceService: import("../types.js").WorkspaceDirectoryService }} dependencies */
+function createWorkspaceDirectoryActions({ workspaceService }) {
+  return Object.freeze([
+    Object.freeze({
+      id: "workspace.workspaces.create",
+      version: 1,
+      kind: "command",
+      channels: ["api", "assistant_tool", "automation", "internal"],
+      surfaces: ["*"],
+      permission: {
+        require: "authenticated"
+      },
+      input: workspaceResource.operations.create.body,
+      output: null,
+      extensions: {
+        assistant: {
+          description: "Create a workspace for the signed-in user.",
+          output: workspaceResource.operations.create.output,
+          transformResult: (result) => workspaceAssistantSummary(result.value)
+        }
+      },
+      execute: (input, context) => workspaceService.createWorkspaceForAuthenticatedUser(
         resolveActionUser(context, input),
-        input.workspaceSlug,
-        {
-          request: resolveRequest(context),
-          context
+        input,
+        { context }
+      )
+    }),
+    Object.freeze({
+      id: "workspace.workspaces.list",
+      version: 1,
+      kind: "query",
+      channels: ["api", "automation", "internal"],
+      surfaces: ["*"],
+      permission: {
+        require: "authenticated"
+      },
+      input: emptyInputValidator,
+      output: null,
+      extensions: {
+        assistant: {
+          description: "List workspaces accessible to the signed-in user.",
+          output: workspaceResource.operations.list.output,
+          transformResult: (result) => ({
+            items: result.value.items.map(({ id, slug, name, avatarUrl, roleSid, isAccessible }) =>
+              ({ id, slug, name, avatarUrl, roleSid, isAccessible })),
+            nextCursor: result.value.nextCursor
+          })
         }
-      ));
-    }
-  },
-  {
-    id: "workspace.workspaces.update",
-    version: 1,
-    kind: "command",
-    channels: ["api", "assistant_tool", "automation", "internal"],
-    surfaces: ["*"],
-    permission: {
-      require: "all",
-      permissions: ["workspace.settings.update"]
-    },
-    input: workspaceUpdateInputValidator,
-    output: null,
-    extensions: {
-      assistant: {
-        description: "Update the active workspace name or avatar URL.",
-        output: workspaceResource.operations.patch.output,
-        transformResult: (result) => workspaceAssistantSummary(result.value)
-      }
-    },
-    idempotency: "optional",
-    async run(workspaceService, input, context) {
-      const { workspaceSlug, ...patch } = input;
-      return returnJsonApiData(await workspaceService.updateWorkspaceForAuthenticatedUser(
+      },
+      execute: (input, context) => workspaceService.listWorkspacesForAuthenticatedUser(
         resolveActionUser(context, input),
-        workspaceSlug,
-        patch,
-        {
-          request: resolveRequest(context),
-          context
+        { context }
+      )
+    }),
+    Object.freeze({
+      id: "workspace.workspaces.read",
+      version: 1,
+      kind: "query",
+      channels: ["api", "automation", "internal"],
+      surfaces: ["*"],
+      permission: {
+        require: "any",
+        permissions: ["workspace.settings.view", "workspace.settings.update"]
+      },
+      input: workspaceSlugParamsValidator,
+      output: null,
+      extensions: {
+        assistant: {
+          description: "Read the active workspace profile.",
+          output: workspaceResource.operations.view.output,
+          transformResult: (result) => workspaceAssistantSummary(result.value)
         }
-      ));
-    }
-  }
-]);
-
-function buildWorkspaceDirectoryActions({ workspaceService } = {}) {
-  if (!workspaceService) throw new TypeError("buildWorkspaceDirectoryActions requires workspaceService.");
-  return workspaceDirectoryActionSpecifications.map(({ run, ...definition }) => Object.freeze({
-    ...definition,
-    execute(input, context) {
-      return run(workspaceService, input, context);
-    }
-  }));
+      },
+      execute: (input, context) => workspaceService.getWorkspaceForAuthenticatedUser(
+        resolveActionUser(context, input),
+        input.workspaceSlug,
+        { context }
+      )
+    }),
+    Object.freeze({
+      id: "workspace.workspaces.update",
+      version: 1,
+      kind: "command",
+      channels: ["api", "assistant_tool", "automation", "internal"],
+      surfaces: ["*"],
+      permission: {
+        require: "all",
+        permissions: ["workspace.settings.update"]
+      },
+      input: workspaceUpdateInputValidator,
+      output: null,
+      extensions: {
+        assistant: {
+          description: "Update the active workspace name or avatar URL.",
+          output: workspaceResource.operations.patch.output,
+          transformResult: (result) => workspaceAssistantSummary(result.value)
+        }
+      },
+      execute: (input, context) => workspaceService.updateWorkspaceForAuthenticatedUser(
+        resolveActionUser(context, input),
+        input.workspaceSlug,
+        input,
+        { context }
+      )
+    })
+  ]);
 }
 
-export { workspaceDirectoryActionSpecifications, buildWorkspaceDirectoryActions };
+export { createWorkspaceDirectoryActions };

package/src/server/workspaceDirectory/{bootWorkspaceDirectoryRoutes.js → workspaceDirectoryRoutes.js}

@@ -7,28 +7,16 @@ import {
   WORKSPACES_COLLECTION_TRANSPORT,
   WORKSPACES_TRANSPORT
 } from "../../shared/jsonApiTransports.js";
-import { resolveWorkspaceRoutePath } from "../common/support/workspaceRoutePaths.js";
+import { resolveWorkspaceRecordId } from "../common/support/workspaceRecordId.js";
+import { resolveWorkspaceRoutePath } from "../support/workspaceRoutePaths.js";
 import { workspaceSlugParamsValidator } from "../common/validators/routeParamsValidator.js";
 import { resolveDefaultWorkspaceRouteSurfaceIdFromAppConfig } from "../support/workspaceActionSurfaces.js";
 
-function resolveWorkspaceRecordId(record = {}, context = {}) {
-  const workspaceId = record?.workspace?.id ?? record?.id;
-  if (workspaceId != null && String(workspaceId).trim()) {
-    return workspaceId;
-  }
-
-  const workspaceSlug = context?.request?.params?.workspaceSlug;
-  if (workspaceSlug != null && String(workspaceSlug).trim()) {
-    return workspaceSlug;
-  }
-
-  throw new Error("Workspace JSON:API response requires workspace id.");
-}
-
-function registerWorkspaceDirectoryRoutes(router, { config = {}, workspaceSelfCreateEnabled = false } = {}) {
-  if (!router || typeof router.register !== "function") {
-    throw new TypeError("registerWorkspaceDirectoryRoutes requires router.register().");
-  }
+/**
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeRouter} router
+ * @param {{ config: import("@jskit-ai/kernel/server/types").RuntimeConfig, workspaceSelfCreateEnabled: boolean }} options
+ */
+function registerWorkspaceDirectoryRoutes(router, { config, workspaceSelfCreateEnabled }) {
   const workspaceRouteSurfaceId = resolveDefaultWorkspaceRouteSurfaceIdFromAppConfig(config);
 
   if (workspaceSelfCreateEnabled) {

package/src/server/workspaceMembers/defaultWorkspaceInviteEmail.js

@@ -1,13 +1,5 @@
-import { createWorkspacesServerI18n } from "../i18n.js";
-
-const englishI18n = createWorkspacesServerI18n();
-
-function english(key, params) {
-  return englishI18n.t("en", key, params);
-}
-
-function escapeHtml(value = "") {
-  return String(value ?? "")
+function escapeHtml(value) {
+  return String(value)
     .replaceAll("&", "&")
     .replaceAll("<", "&lt;")
     .replaceAll(">", "&gt;")
@@ -15,35 +7,29 @@ function escapeHtml(value = "") {
     .replaceAll("'", "&#39;");
 }
 
-// t renders a message in the recipient's language. The markup stays here; each
-// translated fragment, parameters included, is escaped before it enters the HTML.
-function renderDefaultWorkspaceInviteEmail({
-  inviteUrl = "",
-  workspace = {},
-  inviter = null,
-  roleSid = "member",
-  roleLabel = "",
-  expiresAt = "",
-  t = english
-} = {}) {
+/**
+ * The `workspaces.invite-email-template` default. t renders a message in the
+ * recipient's language. The markup stays here; each translated fragment,
+ * parameters included, is escaped before it enters the HTML.
+ * @type {import("../types.js").WorkspaceInviteEmailTemplate}
+ */
+function renderDefaultWorkspaceInviteEmail({ inviteUrl, workspace, inviter, roleSid, roleLabel, expiresAt, t }) {
   const workspaceName =
-    String(workspace?.name || workspace?.slug || "").trim() || t("jskit.workspaces.inviteEmail.workspaceFallback");
+    String(workspace.name || workspace.slug || "").trim() || t("jskit.workspaces.inviteEmail.workspaceFallback");
   const inviterName = String(inviter?.displayName || inviter?.email || "").trim();
-  const roleName = (typeof roleLabel === "string" ? roleLabel.trim() : "") || String(roleSid || "member").trim() || "member";
-  const expiryText = expiresAt ? t("jskit.workspaces.inviteEmail.expiry", { expiresAt }) : "";
+  const roleName = roleLabel || roleSid;
+  const expiryText = t("jskit.workspaces.inviteEmail.expiry", { expiresAt });
   const intro = inviterName
     ? t("jskit.workspaces.inviteEmail.introFromInviter", { inviter: inviterName, workspace: workspaceName, role: roleName })
     : t("jskit.workspaces.inviteEmail.intro", { workspace: workspaceName, role: roleName });
   const subject = t("jskit.workspaces.inviteEmail.subject", { workspace: workspaceName });
-  const text = [intro, expiryText, t("jskit.workspaces.inviteEmail.openLink"), inviteUrl]
-    .filter(Boolean)
-    .join("\n\n");
+  const text = [intro, expiryText, t("jskit.workspaces.inviteEmail.openLink"), inviteUrl].join("\n\n");
   const html = [
     `<p>${escapeHtml(intro)}</p>`,
-    expiryText ? `<p>${escapeHtml(expiryText)}</p>` : "",
+    `<p>${escapeHtml(expiryText)}</p>`,
     `<p><a href="${escapeHtml(inviteUrl)}">${escapeHtml(t("jskit.workspaces.inviteEmail.accept"))}</a></p>`,
     `<p>${escapeHtml(inviteUrl)}</p>`
-  ].filter(Boolean).join("\n");
+  ].join("\n");
 
   return {
     subject,

package/src/server/workspaceMembers/unconfiguredWorkspaceInviteMailer.js

@@ -0,0 +1,25 @@
+/** The delivery outcome of an invitation when no feature provides a mailer. */
+function buildMailerUnconfiguredDelivery() {
+  return {
+    status: "mailer_unconfigured",
+    message: "No workspace invite mailer is configured.",
+    messageCode: "workspaces.invite.mailerUnconfigured",
+    messageParams: {},
+    providerMessageId: ""
+  };
+}
+
+/**
+ * The `workspaces.invite-mailer` default when no feature provides one: invitations
+ * are still created, and their delivery reports that no mailer is configured.
+ * The members service recognizes it and answers that outcome without
+ * rendering the email.
+ * @type {import("../types.js").WorkspaceInviteMailer}
+ */
+const unconfiguredWorkspaceInviteMailer = Object.freeze({
+  async sendWorkspaceInvite() {
+    return buildMailerUnconfiguredDelivery();
+  }
+});
+
+export { buildMailerUnconfiguredDelivery, unconfiguredWorkspaceInviteMailer };

package/src/server/workspaceMembers/workspaceInviteUrls.js

@@ -1,14 +1,17 @@
-function normalizeInvitePathTemplate(value = "") {
+const DEFAULT_INVITE_PATH = "/invite/:token";
+
+// The configured invite path as an absolute path template.
+function normalizeInvitePathTemplate(value) {
   const raw = String(value || "").trim();
   if (!raw) {
-    return "/invite/:token";
+    return DEFAULT_INVITE_PATH;
   }
   return raw.startsWith("/") ? raw : `/${raw}`;
 }
 
-function buildInvitePath(token, pathTemplate = "/invite/:token") {
+// The invite path for a token: the template's :token or [token] replaced, else the token appended.
+function buildInvitePath(token, template) {
   const encodedToken = encodeURIComponent(String(token || "").trim());
-  const template = normalizeInvitePathTemplate(pathTemplate);
   if (template.includes(":token")) {
     return template.replaceAll(":token", encodedToken);
   }
@@ -18,7 +21,8 @@ function buildInvitePath(token, pathTemplate = "/invite/:token") {
   return `${template.replace(/\/$/, "")}/${encodedToken}`;
 }
 
-function normalizeBaseUrl(value = "") {
+// An http(s) base URL without its trailing slash, or "" for anything else.
+function normalizeBaseUrl(value) {
   const raw = String(value || "").trim();
   if (!raw) {
     return "";
@@ -34,23 +38,23 @@ function normalizeBaseUrl(value = "") {
   }
 }
 
-function createWorkspaceInviteUrlBuilder({
-  appConfig = {},
-  env = {}
-} = {}) {
-  const inviteConfig = appConfig?.workspaceInvitations && typeof appConfig.workspaceInvitations === "object"
+/**
+ * The invitation URL builder: `workspaceInvitations.invitePath` (default
+ * /invite/:token) under `workspaceInvitations.inviteBaseUrl`, else the app's
+ * `appPublicUrl`, else APP_PUBLIC_URL; a relative path when none is set.
+ * @param {object} sources
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeConfig} sources.appConfig
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} sources.env
+ */
+function createWorkspaceInviteUrlBuilder({ appConfig, env }) {
+  const inviteConfig = appConfig.workspaceInvitations && typeof appConfig.workspaceInvitations === "object"
     ? appConfig.workspaceInvitations
     : {};
-  const baseUrl = normalizeBaseUrl(
-    inviteConfig.inviteBaseUrl ||
-      inviteConfig.baseUrl ||
-      appConfig?.appPublicUrl ||
-      env.APP_PUBLIC_URL ||
-      ""
-  );
-  const pathTemplate = normalizeInvitePathTemplate(inviteConfig.invitePath || inviteConfig.path || "/invite/:token");
+  const baseUrl = normalizeBaseUrl(inviteConfig.inviteBaseUrl || appConfig.appPublicUrl || env.APP_PUBLIC_URL);
+  const pathTemplate = normalizeInvitePathTemplate(inviteConfig.invitePath);
 
-  return function buildWorkspaceInviteUrl({ token } = {}) {
+  /** @param {{ token: string, invite?: object, workspace?: object }} invite */
+  return function buildWorkspaceInviteUrl({ token }) {
     const invitePath = buildInvitePath(token, pathTemplate);
     if (!baseUrl) {
       return invitePath;
@@ -59,7 +63,4 @@ function createWorkspaceInviteUrlBuilder({
   };
 }
 
-export {
-  buildInvitePath,
-  createWorkspaceInviteUrlBuilder
-};
+export { createWorkspaceInviteUrlBuilder };