@jskit-ai/workspaces-core 0.1.14 → 0.1.16

package/src/server/common/support/realtimeServiceEvents.js

@@ -0,0 +1,91 @@
+import { normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
+import { deepFreeze } from "./deepFreeze.js";
+
+function resolveActorScopedEntityId({ options } = {}) {
+  return normalizeRecordId(options?.context?.actor?.id, { fallback: "" });
+}
+
+function resolveWorkspaceSlugPayload({ args } = {}) {
+  return {
+    workspaceSlug: String(args?.[0]?.slug || "").trim()
+  };
+}
+
+const ACCOUNT_SETTINGS_AND_BOOTSTRAP_EVENTS = deepFreeze([
+  {
+    type: "entity.changed",
+    source: "account",
+    entity: "settings",
+    operation: "updated",
+    entityId: resolveActorScopedEntityId,
+    realtime: {
+      event: "account.settings.changed",
+      audience: "actor_user"
+    }
+  },
+  {
+    type: "entity.changed",
+    source: "users",
+    entity: "bootstrap",
+    operation: "updated",
+    entityId: resolveActorScopedEntityId,
+    realtime: {
+      event: "users.bootstrap.changed",
+      audience: "actor_user"
+    }
+  }
+]);
+
+function createWorkspaceEntityAndBootstrapEvents({
+  workspaceEntity,
+  workspaceOperation,
+  workspaceRealtimeEvent,
+  workspaceEntityId = ({ args }) => args?.[0]?.id,
+  bootstrapEntityId = ({ args }) => args?.[0]?.id,
+  bootstrapAudience = "event_scope"
+} = {}) {
+  const normalizedWorkspaceEntity = String(workspaceEntity || "").trim();
+  const normalizedWorkspaceOperation = String(workspaceOperation || "")
+    .trim()
+    .toLowerCase();
+  const normalizedWorkspaceRealtimeEvent = String(workspaceRealtimeEvent || "").trim();
+  if (!normalizedWorkspaceEntity || !normalizedWorkspaceOperation || !normalizedWorkspaceRealtimeEvent) {
+    throw new Error(
+      "createWorkspaceEntityAndBootstrapEvents requires workspaceEntity, workspaceOperation, and workspaceRealtimeEvent."
+    );
+  }
+  if (typeof workspaceEntityId !== "function") {
+    throw new Error("createWorkspaceEntityAndBootstrapEvents requires workspaceEntityId to be a function.");
+  }
+  if (typeof bootstrapEntityId !== "function") {
+    throw new Error("createWorkspaceEntityAndBootstrapEvents requires bootstrapEntityId to be a function.");
+  }
+
+  return deepFreeze([
+    {
+      type: "entity.changed",
+      source: "workspace",
+      entity: normalizedWorkspaceEntity,
+      operation: normalizedWorkspaceOperation,
+      entityId: (payload = {}) => normalizeRecordId(workspaceEntityId(payload), { fallback: "" }),
+      realtime: {
+        event: normalizedWorkspaceRealtimeEvent,
+        payload: resolveWorkspaceSlugPayload,
+        audience: "event_scope"
+      }
+    },
+    {
+      type: "entity.changed",
+      source: "users",
+      entity: "bootstrap",
+      operation: "updated",
+      entityId: (payload = {}) => normalizeRecordId(bootstrapEntityId(payload), { fallback: "" }),
+      realtime: {
+        event: "users.bootstrap.changed",
+        audience: bootstrapAudience
+      }
+    }
+  ]);
+}
+
+export { ACCOUNT_SETTINGS_AND_BOOTSTRAP_EVENTS, createWorkspaceEntityAndBootstrapEvents };

package/src/server/common/support/resolveActionUser.js

@@ -0,0 +1,9 @@
+import { normalizeObject } from "@jskit-ai/kernel/shared/support/normalize";
+
+function resolveActionUser(context, input) {
+  const payload = normalizeObject(input);
+  const request = context?.requestMeta?.request || null;
+  return payload.user || request?.user || context?.actor || null;
+}
+
+export { resolveActionUser };

package/src/server/common/support/workspaceRoutePaths.js

@@ -0,0 +1,18 @@
+import { resolveScopedApiBasePath } from "@jskit-ai/kernel/shared/surface";
+import { normalizePathname } from "@jskit-ai/kernel/shared/surface/paths";
+
+const WORKSPACE_ROUTE_BASE_PATH = resolveScopedApiBasePath({
+  routeBase: "/w/:workspaceSlug",
+  strictParams: false
+});
+
+function resolveWorkspaceRoutePath(relativePath = "/") {
+  const normalizedRelativePath = normalizePathname(relativePath || "/");
+  if (normalizedRelativePath === "/") {
+    return WORKSPACE_ROUTE_BASE_PATH;
+  }
+
+  return `${WORKSPACE_ROUTE_BASE_PATH}${normalizedRelativePath}`;
+}
+
+export { WORKSPACE_ROUTE_BASE_PATH, resolveWorkspaceRoutePath };

package/src/server/common/validators/authenticatedUserValidator.js

@@ -0,0 +1,43 @@
+import { Type } from "@fastify/type-provider-typebox";
+import { normalizeObjectInput, recordIdInputSchema } from "@jskit-ai/kernel/shared/validators";
+import { normalizeLowerText, normalizeText } from "@jskit-ai/kernel/shared/actions/textNormalization";
+import { normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
+
+function normalizeAuthenticatedUser(input = {}) {
+  const source = normalizeObjectInput(input);
+  const id = normalizeRecordId(source.id, { fallback: null });
+  if (!id) {
+    return null;
+  }
+
+  const email = normalizeLowerText(source.email);
+  return {
+    id,
+    email,
+    username: normalizeLowerText(source.username),
+    displayName: normalizeText(source.displayName) || email || `User ${id}`,
+    authProvider: normalizeLowerText(source.authProvider),
+    authProviderUserSid: normalizeText(source.authProviderUserSid),
+    avatarStorageKey: source.avatarStorageKey ? normalizeText(source.avatarStorageKey) : null,
+    avatarVersion: source.avatarVersion == null ? null : String(source.avatarVersion)
+  };
+}
+
+const authenticatedUserValidator = Object.freeze({
+  schema: Type.Object(
+    {
+      id: recordIdInputSchema,
+      email: Type.String({ minLength: 1 }),
+      username: Type.Optional(Type.String()),
+      displayName: Type.Optional(Type.String()),
+      authProvider: Type.Optional(Type.String()),
+      authProviderUserSid: Type.Optional(Type.String()),
+      avatarStorageKey: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+      avatarVersion: Type.Optional(Type.Union([Type.String(), Type.Number(), Type.Null()]))
+    },
+    { additionalProperties: true }
+  ),
+  normalize: normalizeAuthenticatedUser
+});
+
+export { authenticatedUserValidator };

package/src/server/common/validators/routeParamsValidator.js

@@ -0,0 +1,62 @@
+import { Type } from "@fastify/type-provider-typebox";
+import { normalizeObjectInput } from "@jskit-ai/kernel/shared/validators/inputNormalization";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+function normalizeRouteParams(input = {}) {
+  const source = normalizeObjectInput(input);
+  const normalized = {};
+
+  if (Object.hasOwn(source, "workspaceSlug")) {
+    normalized.workspaceSlug = normalizeText(source.workspaceSlug).toLowerCase();
+  }
+
+  if (Object.hasOwn(source, "memberUserId")) {
+    normalized.memberUserId = normalizeText(source.memberUserId);
+  }
+
+  if (Object.hasOwn(source, "inviteId")) {
+    normalized.inviteId = normalizeText(source.inviteId);
+  }
+
+  if (Object.hasOwn(source, "provider")) {
+    normalized.provider = normalizeText(source.provider);
+  }
+
+  return normalized;
+}
+
+function normalizeWorkspaceSlugParams(input = {}) {
+  const source = normalizeObjectInput(input);
+  const normalized = {};
+
+  if (Object.hasOwn(source, "workspaceSlug")) {
+    normalized.workspaceSlug = normalizeText(source.workspaceSlug).toLowerCase();
+  }
+
+  return normalized;
+}
+
+const routeParamsValidator = Object.freeze({
+  schema: Type.Object(
+    {
+      workspaceSlug: Type.Optional(Type.String({ minLength: 1 })),
+      memberUserId: Type.Optional(Type.String({ minLength: 1 })),
+      inviteId: Type.Optional(Type.String({ minLength: 1 })),
+      provider: Type.Optional(Type.String({ minLength: 1 }))
+    },
+    { additionalProperties: false }
+  ),
+  normalize: normalizeRouteParams
+});
+
+const workspaceSlugParamsValidator = Object.freeze({
+  schema: Type.Object(
+    {
+      workspaceSlug: Type.Optional(Type.String({ minLength: 1 }))
+    },
+    { additionalProperties: false }
+  ),
+  normalize: normalizeWorkspaceSlugParams
+});
+
+export { routeParamsValidator, workspaceSlugParamsValidator };

package/src/server/registerWorkspaceBootstrap.js

@@ -0,0 +1,27 @@
+import { registerBootstrapPayloadContributor } from "@jskit-ai/kernel/server/runtime";
+import { resolveAppConfig } from "@jskit-ai/kernel/server/support";
+import { createWorkspaceBootstrapContributor } from "./workspaceBootstrapContributor.js";
+
+
+function registerWorkspaceBootstrap(app) {
+  if (!app || typeof app.singleton !== "function") {
+    throw new Error("registerWorkspaceBootstrap requires application singleton().");
+  }
+
+  registerBootstrapPayloadContributor(app, "workspaces.core.bootstrap.payloadContributor", (scope) => {
+    const workspaceInvitationsEnabled = scope.make("workspaces.invitations.enabled");
+
+    return createWorkspaceBootstrapContributor({
+      workspaceService: scope.make("workspaces.service"),
+      workspacePendingInvitationsService: workspaceInvitationsEnabled
+        ? scope.make("users.workspace.pending-invitations.service")
+        : null,
+      workspaceInvitationsEnabled,
+      usersRepository: scope.make("usersRepository"),
+      appConfig: resolveAppConfig(scope),
+      tenancyProfile: scope.make("workspaces.tenancy.profile")
+    });
+  });
+}
+
+export { registerWorkspaceBootstrap };

package/src/server/registerWorkspaceCore.js

@@ -0,0 +1,100 @@
+import {
+  registerActionContextContributor
+} from "@jskit-ai/kernel/server/actions";
+import { registerRouteVisibilityResolver } from "@jskit-ai/kernel/server/http";
+import { resolveAppConfig } from "@jskit-ai/kernel/server/support";
+import { registerProfileSyncLifecycleContributor } from "@jskit-ai/users-core/server/profileSyncLifecycleContributorRegistry";
+import { createService as createWorkspaceService } from "./common/services/workspaceContextService.js";
+import { createWorkspaceActionContextContributor } from "./common/contributors/workspaceActionContextContributor.js";
+import { createWorkspaceRouteVisibilityResolver } from "./common/contributors/workspaceRouteVisibilityResolver.js";
+import { createWorkspaceAuthPolicyContextResolver } from "./common/contributors/workspaceAuthPolicyContextResolver.js";
+import { TENANCY_MODE_WORKSPACES, resolveTenancyProfile } from "../shared/tenancyProfile.js";
+import { resolveWorkspaceInvitationsPolicy } from "./support/workspaceInvitationsPolicy.js";
+import {
+  registerWorkspaceActionSurfaceSources,
+  resolveWorkspaceSurfaceIdsFromAppConfig
+} from "./support/workspaceActionSurfaces.js";
+
+
+function registerWorkspaceCore(app) {
+  if (!app || typeof app.singleton !== "function") {
+    throw new Error("registerWorkspaceCore requires application singleton().");
+  }
+
+  registerWorkspaceActionSurfaceSources(app);
+
+  app.singleton("workspaces.tenancy.profile", (scope) => {
+    const appConfig = resolveAppConfig(scope);
+    return resolveTenancyProfile(appConfig);
+  });
+
+  app.singleton("workspaces.service", (scope) => {
+    const appConfig = resolveAppConfig(scope);
+    return createWorkspaceService({
+      appConfig,
+      workspacesRepository: scope.make("workspacesRepository"),
+      workspaceMembershipsRepository: scope.make("workspaceMembershipsRepository"),
+      workspaceSettingsRepository: scope.make("workspaceSettingsRepository")
+    });
+  });
+  app.singleton("workspaces.enabled", (scope) => {
+    return scope.make("workspaces.tenancy.profile").workspace.enabled === true;
+  });
+
+  app.singleton("workspaces.self-create.enabled", (scope) => {
+    return scope.make("workspaces.tenancy.profile").workspace.allowSelfCreate === true;
+  });
+
+  app.singleton("workspaces.tenancy.enabled", (scope) => {
+    return scope.make("workspaces.tenancy.profile").mode === TENANCY_MODE_WORKSPACES;
+  });
+
+  app.singleton("workspaces.invitations.enabled", (scope) => {
+    const appConfig = resolveAppConfig(scope);
+    const tenancyProfile = scope.make("workspaces.tenancy.profile");
+    return resolveWorkspaceInvitationsPolicy({
+      appConfig,
+      tenancyProfile
+    }).enabled;
+  });
+
+  registerProfileSyncLifecycleContributor(app, "workspaces.core.profileSyncLifecycleContributor", (scope) => {
+    const workspaceService = scope.make("workspaces.service");
+
+    return Object.freeze({
+      contributorId: "workspaces.core.profileSync",
+      order: 100,
+      async afterIdentityProfileSynced({ profile, created, options } = {}) {
+        if (!created || !profile || typeof workspaceService?.provisionWorkspaceForNewUser !== "function") {
+          return;
+        }
+
+        await workspaceService.provisionWorkspaceForNewUser(profile, options);
+      }
+    });
+  });
+
+  registerActionContextContributor(app, "users.core.workspace.actionContextContributor", (scope) => {
+    const appConfig = resolveAppConfig(scope);
+    return createWorkspaceActionContextContributor({
+      workspaceService: scope.make("workspaces.service"),
+      workspaceSurfaceIds: resolveWorkspaceSurfaceIdsFromAppConfig(appConfig)
+    });
+  });
+
+  if (typeof app.has !== "function" || !app.has("auth.policy.contextResolver")) {
+    app.singleton("auth.policy.contextResolver", (scope) =>
+      createWorkspaceAuthPolicyContextResolver({
+        workspaceService: scope.make("workspaces.service")
+      })
+    );
+  }
+
+  registerRouteVisibilityResolver(app, "users.core.workspace.routeVisibilityResolver", (scope) =>
+    createWorkspaceRouteVisibilityResolver({
+      workspaceService: scope.make("workspaces.service")
+    })
+  );
+}
+
+export { registerWorkspaceCore };

package/src/server/registerWorkspaceRepositories.js

@@ -0,0 +1,26 @@
+import { createRepository as createWorkspacesRepository } from "./common/repositories/workspacesRepository.js";
+import { createRepository as createWorkspaceMembershipsRepository } from "./common/repositories/workspaceMembershipsRepository.js";
+import { createRepository as createWorkspaceInvitesRepository } from "./common/repositories/workspaceInvitesRepository.js";
+
+function registerWorkspaceRepositories(app) {
+  if (!app || typeof app.singleton !== "function") {
+    throw new Error("registerWorkspaceRepositories requires application singleton().");
+  }
+
+  app.singleton("workspacesRepository", (scope) => {
+    const knex = scope.make("jskit.database.knex");
+    return createWorkspacesRepository(knex);
+  });
+
+  app.singleton("workspaceMembershipsRepository", (scope) => {
+    const knex = scope.make("jskit.database.knex");
+    return createWorkspaceMembershipsRepository(knex);
+  });
+
+  app.singleton("workspaceInvitesRepository", (scope) => {
+    const knex = scope.make("jskit.database.knex");
+    return createWorkspaceInvitesRepository(knex);
+  });
+}
+
+export { registerWorkspaceRepositories };

package/src/server/support/resolveWorkspace.js

@@ -0,0 +1,16 @@
+import { normalizeObject } from "@jskit-ai/kernel/shared/support/normalize";
+
+function resolveRequest(context = {}) {
+  const requestMeta = normalizeObject(context?.requestMeta);
+  return normalizeObject(requestMeta.request);
+}
+
+function resolveWorkspace(context = {}, input = {}) {
+  const payload = normalizeObject(input);
+  const requestMeta = normalizeObject(context?.requestMeta);
+  const resolvedWorkspaceContext = normalizeObject(requestMeta.resolvedWorkspaceContext);
+
+  return payload.workspace || resolvedWorkspaceContext.workspace || context?.workspace || resolveRequest(context)?.workspace || null;
+}
+
+export { resolveWorkspace };

package/src/server/support/workspaceActionSurfaces.js

@@ -0,0 +1,118 @@
+import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+import { resolveDefaultWorkspaceSurfaceId } from "../../shared/support/workspacePathModel.js";
+
+function normalizeSurfaceIds(surfaceIds = []) {
+  const source = Array.isArray(surfaceIds) ? surfaceIds : [];
+  const seen = new Set();
+  const normalized = [];
+
+  for (const candidate of source) {
+    const surfaceId = normalizeSurfaceId(candidate);
+    if (!surfaceId || seen.has(surfaceId)) {
+      continue;
+    }
+    seen.add(surfaceId);
+    normalized.push(surfaceId);
+  }
+
+  return normalized;
+}
+
+function resolveWorkspaceSurfaceIdsFromAppConfig(appConfig = {}) {
+  return resolveSurfaceIdsFromAppConfig(appConfig, (definition) => definition.requiresWorkspace === true);
+}
+
+function resolveSurfaceIdsFromAppConfig(appConfig = {}, predicate) {
+  const source = isRecord(appConfig?.surfaceDefinitions) ? appConfig.surfaceDefinitions : {};
+  const resolved = [];
+
+  for (const [key, value] of Object.entries(source)) {
+    const definition = isRecord(value) ? value : {};
+    const surfaceId = normalizeSurfaceId(definition.id || key);
+    if (!surfaceId) {
+      continue;
+    }
+    if (definition.enabled === false) {
+      continue;
+    }
+    if (typeof predicate === "function" && predicate(definition) === true) {
+      resolved.push(surfaceId);
+    }
+  }
+
+  return normalizeSurfaceIds(resolved);
+}
+
+function materializeWorkspaceActionSurfaces(actions = [], { workspaceSurfaceIds = [] } = {}) {
+  const sourceActions = Array.isArray(actions) ? actions : [];
+  const resolvedWorkspaceSurfaceIds = normalizeSurfaceIds(workspaceSurfaceIds);
+  const materialized = [];
+
+  for (const entry of sourceActions) {
+    const action = isRecord(entry) ? entry : {};
+    const surfacesFrom = String(action.surfacesFrom || "")
+      .trim()
+      .toLowerCase();
+    if (surfacesFrom !== "workspace") {
+      materialized.push(action);
+      continue;
+    }
+
+    if (resolvedWorkspaceSurfaceIds.length < 1) {
+      continue;
+    }
+
+    const { surfacesFrom: _ignored, ...rest } = action;
+    materialized.push({
+      ...rest,
+      surfaces: [...resolvedWorkspaceSurfaceIds]
+    });
+  }
+
+  return Object.freeze(materialized.map((entry) => Object.freeze({ ...entry })));
+}
+
+function registerWorkspaceActionSurfaceSources(app) {
+  if (!app || typeof app.actionSurfaceSource !== "function") {
+    return;
+  }
+
+  app.actionSurfaceSource("workspace", ({ scope }) => {
+    const appConfig = scope?.has?.("appConfig") ? scope.make("appConfig") : {};
+    return resolveWorkspaceSurfaceIdsFromAppConfig(appConfig);
+  });
+}
+
+function materializeWorkspaceActionSurfacesFromAppConfig(actions = [], { appConfig = {} } = {}) {
+  const workspaceSurfaceIds = resolveWorkspaceSurfaceIdsFromAppConfig(appConfig);
+  return materializeWorkspaceActionSurfaces(actions, { workspaceSurfaceIds });
+}
+
+function resolveDefaultWorkspaceRouteSurfaceIdFromAppConfig(appConfig = {}) {
+  const workspaceSurfaceIds = resolveWorkspaceSurfaceIdsFromAppConfig(appConfig);
+  const workspaceSurfaceSet = new Set(workspaceSurfaceIds);
+
+  const resolvedSurfaceId = resolveDefaultWorkspaceSurfaceId({
+    defaultSurfaceId: appConfig?.surfaceDefaultId,
+    workspaceSurfaceIds,
+    surfaceRequiresWorkspace(surfaceId) {
+      return workspaceSurfaceSet.has(surfaceId);
+    }
+  });
+
+  return (
+    normalizeSurfaceId(resolvedSurfaceId) ||
+    normalizeSurfaceId(workspaceSurfaceIds[0]) ||
+    normalizeSurfaceId(appConfig?.surfaceDefaultId) ||
+    ""
+  );
+}
+
+export {
+  resolveWorkspaceSurfaceIdsFromAppConfig,
+  resolveDefaultWorkspaceRouteSurfaceIdFromAppConfig,
+  materializeWorkspaceActionSurfaces,
+  materializeWorkspaceActionSurfacesFromAppConfig,
+  registerWorkspaceActionSurfaceSources
+};

package/src/server/support/workspaceInvitationsPolicy.js

@@ -0,0 +1,45 @@
+import {
+  TENANCY_MODE_NONE,
+  TENANCY_MODE_PERSONAL,
+  normalizeTenancyMode
+} from "../../shared/tenancyMode.js";
+
+function normalizeWorkspaceInvitationsConfig(appConfig = {}) {
+  const source = appConfig && typeof appConfig === "object" && !Array.isArray(appConfig)
+    ? appConfig.workspaceInvitations
+    : null;
+  const normalizedSource = source && typeof source === "object" && !Array.isArray(source)
+    ? source
+    : {};
+
+  return Object.freeze({
+    enabled: normalizedSource.enabled !== false,
+    allowInPersonalMode: normalizedSource.allowInPersonalMode !== false
+  });
+}
+
+function resolveWorkspaceInvitationsPolicy({
+  appConfig = {},
+  tenancyProfile = null
+} = {}) {
+  const config = normalizeWorkspaceInvitationsConfig(appConfig);
+  const normalizedTenancyProfile = tenancyProfile && typeof tenancyProfile === "object"
+    ? tenancyProfile
+    : {};
+  const tenancyMode = normalizeTenancyMode(normalizedTenancyProfile.mode || appConfig?.tenancyMode);
+  const workspaceEnabled = normalizedTenancyProfile?.workspace?.enabled === true || tenancyMode !== TENANCY_MODE_NONE;
+  const enabledForTenancyMode = tenancyMode !== TENANCY_MODE_PERSONAL || config.allowInPersonalMode === true;
+  const enabled = config.enabled === true && workspaceEnabled && enabledForTenancyMode;
+
+  return Object.freeze({
+    enabled,
+    workspaceEnabled,
+    allowInPersonalMode: config.allowInPersonalMode,
+    tenancyMode
+  });
+}
+
+export {
+  normalizeWorkspaceInvitationsConfig,
+  resolveWorkspaceInvitationsPolicy
+};

package/src/server/support/workspaceRouteInput.js

@@ -0,0 +1,22 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+function readWorkspaceSlugFromRouteParams(params = {}) {
+  const workspaceSlug = normalizeText(params?.workspaceSlug).toLowerCase();
+  return workspaceSlug || "";
+}
+
+function buildWorkspaceInputFromRouteParams(params = {}) {
+  const workspaceSlug = readWorkspaceSlugFromRouteParams(params);
+  if (!workspaceSlug) {
+    return {};
+  }
+
+  return {
+    workspaceSlug
+  };
+}
+
+export {
+  readWorkspaceSlugFromRouteParams,
+  buildWorkspaceInputFromRouteParams
+};