feat(061): organizations can be invited to a Space (server#4100)

.devcontainer/docker-compose.yml

@@ -310,7 +310,7 @@ services:
       - "4004:4004"
 
   notification:
-    image: alkemio/notifications:v0.37.0
+    image: alkemio/notifications:v0.39.0
     platform: linux/amd64
     extra_hosts:
       - "host.docker.internal:host-gateway"

alkemio.yml

@@ -534,6 +534,12 @@ notifications:
     enabled: ${CALLOUT_REACTION_NOTIFICATIONS_ENABLED}:true
     email_suppression_window_seconds: ${CALLOUT_REACTION_EMAIL_SUPPRESSION_WINDOW_SECONDS}:300
 
+  # Organization space-invitation notifications. NOT declared on any
+  # deployment manifest this release — the in-code default below governs
+  # everywhere; changing the support escalation address requires a deploy.
+  organization_invitations:
+    support_email: ${NOTIFICATIONS_ORGANIZATION_INVITATION_SUPPORT_EMAIL}:support@alkem.io
+
   # Chat/conversation message notifications (034-messaging-notifications).
   # NOT declared on any deployment manifest this release (Operator Ruling 3b) —
   # the in-code defaults below govern everywhere; flipping `enabled` in

quickstart-services.yml

@@ -433,7 +433,7 @@ services:
       - 'host.docker.internal:host-gateway'
     container_name: alkemio_dev_notifications
     hostname: notifications
-    image: alkemio/notifications:v0.38.0
+    image: alkemio/notifications:v0.39.0
     depends_on:
       rabbitmq:
         condition: service_healthy

schema.graphql

@@ -581,6 +581,8 @@ enum MutationType {
 enum NotificationEvent {
   ORGANIZATION_ADMIN_MENTIONED
   ORGANIZATION_ADMIN_MESSAGE
+  ORGANIZATION_ADMIN_SPACE_COMMUNITY_INVITATION
+  ORGANIZATION_ADMIN_SPACE_COMMUNITY_JOINED
   ORGANIZATION_MESSAGE_SENDER
   PLATFORM_ADMIN_GLOBAL_ROLE_CHANGED
   PLATFORM_ADMIN_SPACE_CREATED
@@ -591,6 +593,10 @@ enum NotificationEvent {
   SPACE_ADMIN_COLLABORATION_CALLOUT_CONTRIBUTION
   SPACE_ADMIN_COMMUNITY_APPLICATION
   SPACE_ADMIN_COMMUNITY_NEW_MEMBER
+  SPACE_ADMIN_ORGANIZATION_COMMUNITY_INVITATION_ACCEPTED
+  SPACE_ADMIN_ORGANIZATION_COMMUNITY_INVITATION_DECLINED
+  SPACE_ADMIN_USER_COMMUNITY_INVITATION_ACCEPTED
+  SPACE_ADMIN_USER_COMMUNITY_INVITATION_DECLINED
   SPACE_ADMIN_VIRTUAL_COMMUNITY_INVITATION_DECLINED
   SPACE_COLLABORATION_CALLOUT_COMMENT
   SPACE_COLLABORATION_CALLOUT_CONTRIBUTION
@@ -798,6 +804,10 @@ enum RoleName {
   REGISTERED
 }
 
+enum RoleSetInvitationResultNotice {
+  ORGANIZATION_HAS_NO_ADMINISTRATORS
+}
+
 enum RoleSetInvitationResultType {
   ALREADY_HAS_OPEN_APPLICATION
   ALREADY_INVITED_TO_PLATFORM_AND_ROLE_SET
@@ -806,6 +816,8 @@ enum RoleSetInvitationResultType {
   INVITATION_TO_PARENT_NOT_AUTHORIZED
   INVITED_TO_PLATFORM_AND_ROLE_SET
   INVITED_TO_ROLE_SET
+  ORGANIZATION_LEAD_ROLE_LIMIT_REACHED
+  ORGANIZATION_NOT_ACCEPTING_INVITATIONS
 }
 
 enum RoleSetRoleImplicit {
@@ -3365,6 +3377,14 @@ type InAppNotificationPayloadSpaceCommunityCalendarEventComment implements InApp
 }
 
 type InAppNotificationPayloadSpaceCommunityInvitation implements InAppNotificationPayload {
+  """
+  The underlying invitation — role(s) offered, whether the parent Space is also joined, and the Spaces that will be joined on acceptance.
+  """
+  invitation: Invitation
+  """
+  The organization the invitation is for, when the invitee is an organization.
+  """
+  organization: Organization
   """The Space that the invitation is for."""
   space: Space!
   """The payload type."""
@@ -3565,6 +3585,10 @@ type Invitation {
   lifecycle: Lifecycle!
   """The next events of this Lifecycle."""
   nextEvents: [String!]!
+  """
+  The Spaces that will be joined if this invitation is accepted, root Space first; null when the caller may not answer this invitation on the invited Actor's behalf.
+  """
+  spacesToJoinOnAccept: [SpaceJoinPreview!]
   """The current state of this Lifecycle."""
   state: String!
   """
@@ -5030,6 +5054,8 @@ type OrganizationSettings {
 }
 
 type OrganizationSettingsMembership {
+  """Allow Spaces to invite this Organization to join them."""
+  allowSpaceInvitations: Boolean!
   """
   Allow Users with email addresses matching the domain of this Organization to join.
   """
@@ -6166,6 +6192,18 @@ type RoleSetInvitationResult {
   """
   application: Application
   invitation: Invitation
+  """
+  The id of the invited actor this result belongs to, when the invitee was an actor or an email that resolved to an existing user.
+  """
+  invitedActorID: UUID
+  """
+  The email address this result belongs to, when the invitee was submitted as an email address.
+  """
+  invitedEmail: String
+  """
+  An informational addendum to the result, set only alongside a successful invite outcome.
+  """
+  notice: RoleSetInvitationResultNotice
   platformInvitation: PlatformInvitation
   type: RoleSetInvitationResultType!
 }
@@ -6612,6 +6650,15 @@ type SpaceAboutMembership {
   roleSetID: UUID!
 }
 
+type SpaceJoinPreview {
+  """The display name of the Space that will be joined."""
+  displayName: String!
+  """The ID of the Space that will be joined."""
+  id: UUID!
+  """The URL of the Space that will be joined."""
+  url: String!
+}
+
 type SpacePendingMembershipInfo {
   """About the Space"""
   about: SpaceAbout!
@@ -7369,6 +7416,10 @@ type UserSettingsNotificationOrganization {
   Receive notification when the organization you are admin of is messaged
   """
   adminMessageReceived: UserSettingsNotificationChannels!
+  """
+  Receive a notification when an organization you administer is invited to a Space
+  """
+  adminSpaceCommunityInvitation: UserSettingsNotificationChannels!
 }
 
 type UserSettingsNotificationPlatform {
@@ -7444,6 +7495,10 @@ type UserSettingsNotificationSpaceAdmin {
   communicationMessageReceived: UserSettingsNotificationChannels!
   """Receive a notification when an application is received"""
   communityApplicationReceived: UserSettingsNotificationChannels!
+  """
+  Receive a notification when someone responds to an invitation you sent (admin)
+  """
+  communityInvitationResponse: UserSettingsNotificationChannels!
   """Receive a notification when a new member joins the community (admin)"""
   communityNewMember: UserSettingsNotificationChannels!
   """
@@ -10134,10 +10189,12 @@ input UpdateOrganizationSettingsInput {
 }
 
 input UpdateOrganizationSettingsMembershipInput {
+  """Allow Spaces to invite this Organization to join them."""
+  allowSpaceInvitations: Boolean
   """
   Allow Users with email addresses matching the domain of this Organization to join.
   """
-  allowUsersMatchingDomainToJoin: Boolean!
+  allowUsersMatchingDomainToJoin: Boolean
 }
 
 input UpdateOrganizationSettingsPrivacyInput {
@@ -10507,6 +10564,10 @@ input UpdateUserSettingsNotificationOrganizationInput {
   Receive notification when the organization you are admin of is messaged
   """
   adminMessageReceived: NotificationSettingInput
+  """
+  Receive a notification when an organization you administer is invited to a Space
+  """
+  adminSpaceCommunityInvitation: NotificationSettingInput
 }
 
 input UpdateUserSettingsNotificationPlatformAdminInput {
@@ -10553,6 +10614,10 @@ input UpdateUserSettingsNotificationSpaceAdminInput {
   communicationMessageReceived: NotificationSettingInput
   """Receive a notification when an application is received"""
   communityApplicationReceived: NotificationSettingInput
+  """
+  Receive a notification when someone responds to an invitation you sent (admin)
+  """
+  communityInvitationResponse: NotificationSettingInput
   """Receive a notification when a new member joins the community (admin)"""
   communityNewMember: NotificationSettingInput
   """

src/common/constants/authorization/index.ts

@@ -1,4 +1,5 @@
 export * from './credential.rule.constants';
 export * from './credential.rule.types.constants';
 export * from './global.policy.constants';
+export * from './organization.manager.credentials';
 export * from './policy.rule.constants';

src/common/constants/authorization/organization.manager.credentials.ts

@@ -0,0 +1,21 @@
+import { AuthorizationCredential } from '@common/enums/authorization.credential';
+
+// The credential types that make a user a manager of an organization —
+// able to act on its behalf (accept/decline invitations, edit settings)
+// regardless of whether they also hold associate membership. Shared by
+// every lookup that needs "who manages this organization" rather than
+// "who is a member of this organization".
+export const ORGANIZATION_MANAGER_CREDENTIAL_TYPES: readonly AuthorizationCredential[] =
+  [
+    AuthorizationCredential.ORGANIZATION_OWNER,
+    AuthorizationCredential.ORGANIZATION_ADMIN,
+  ];
+
+// The credential types that receive an organization's notifications.
+// Deliberately NARROWER than ORGANIZATION_MANAGER_CREDENTIAL_TYPES above:
+// product asked for "all organization admins" only (server#4100 AC,
+// notifications#356 AC and the product email thread all say admins, never
+// owners), so an owner who is not also an admin manages the organization and
+// may accept on its behalf, but is not notified.
+export const ORGANIZATION_NOTIFICATION_CREDENTIAL_TYPES: readonly AuthorizationCredential[] =
+  [AuthorizationCredential.ORGANIZATION_ADMIN];

src/common/constants/entity.field.length.constants.ts

@@ -16,6 +16,15 @@ export const NAMEID_MAX_LENGTH = 25;
 export const NAMEID_MIN_LENGTH = 5;
 // polls
 export const POLL_OPTIONS_MAX_COUNT = 10;
+// role set invitations: caps EACH invitee field independently
+// (`invitedActorIDs` and `invitedUserEmails` each carry their own
+// `@ArrayMaxSize`), so a single mutation's worst-case fan-out is 2x this
+// value. The bound exists to stop an unbounded number of per-invitee guard
+// checks; it is not a per-operation total.
+export const ROLE_SET_INVITE_BATCH_MAX = 100;
+// Upper bound on extraRoles per invite request: there are only a handful of
+// RoleName values, so anything larger is a malformed or hostile payload.
+export const ROLE_SET_INVITE_EXTRA_ROLES_MAX = 10;
 // others
 export const ENUM_LENGTH = 128;
 // https://www.rfc-editor.org/rfc/rfc1034#section-3.1

src/common/enums/community.membership.origin.ts

@@ -0,0 +1,30 @@
+/**
+ * How an actor came to hold a role in a community. Used to suppress the
+ * generic "a new member joined" admin notification when the membership was
+ * the outcome of a step the admins were already notified about, so one event
+ * never produces two notifications.
+ *
+ * The rule is: **suppress only where a replacement notification exists.** An
+ * accepted INVITATION has one -- "X accepted the invitation" reaches every
+ * admin of the invited Space (FR-020) -- so the generic notification would be
+ * the second of a pair, which is what the product brief rules out.
+ *
+ * An approved APPLICATION deliberately has NO member here. There is no
+ * application-approved event to take the suppressed notification's place --
+ * `SPACE_ADMIN_COMMUNITY_APPLICATION` fires at submission, not at approval --
+ * so suppressing it leaves the approving admin's co-admins told nothing at
+ * all. Zero is not one, and that flow is outside what server#4100 changes.
+ * The member is omitted rather than left unused so it cannot be quietly
+ * reintroduced (ruling R40, restoring R31; R35 had briefly added it).
+ *
+ * Adding the missing application-approved event is tracked as
+ * alkem-io/server#6476. If it lands, add the member back here and thread it in
+ * `RoleSetService.ensureMemberOfRoleSetAndAncestors` -- at that point the
+ * replacement exists and the suppression becomes correct.
+ */
+export enum CommunityMembershipOrigin {
+  /** Direct assignment by an admin, a direct join, bootstrap, conversion. */
+  DIRECT = 'DIRECT',
+  /** The actor accepted an invitation to the community. */
+  INVITATION = 'INVITATION',
+}

src/common/enums/notification.event.ts

@@ -14,11 +14,17 @@ export enum NotificationEvent {
   ORGANIZATION_ADMIN_MESSAGE = 'ORGANIZATION_ADMIN_MESSAGE',
   ORGANIZATION_ADMIN_MENTIONED = 'ORGANIZATION_ADMIN_MENTIONED',
   ORGANIZATION_MESSAGE_SENDER = 'ORGANIZATION_MESSAGE_SENDER',
+  ORGANIZATION_ADMIN_SPACE_COMMUNITY_INVITATION = 'ORGANIZATION_ADMIN_SPACE_COMMUNITY_INVITATION',
+  ORGANIZATION_ADMIN_SPACE_COMMUNITY_JOINED = 'ORGANIZATION_ADMIN_SPACE_COMMUNITY_JOINED',
   // space admin
   SPACE_ADMIN_COMMUNITY_APPLICATION = 'SPACE_ADMIN_COMMUNITY_APPLICATION',
   SPACE_ADMIN_COLLABORATION_CALLOUT_CONTRIBUTION = 'SPACE_ADMIN_COLLABORATION_CALLOUT_CONTRIBUTION',
   SPACE_ADMIN_COMMUNITY_NEW_MEMBER = 'SPACE_ADMIN_COMMUNITY_NEW_MEMBER',
   SPACE_ADMIN_VIRTUAL_COMMUNITY_INVITATION_DECLINED = 'SPACE_ADMIN_VIRTUAL_COMMUNITY_INVITATION_DECLINED',
+  SPACE_ADMIN_ORGANIZATION_COMMUNITY_INVITATION_ACCEPTED = 'SPACE_ADMIN_ORGANIZATION_COMMUNITY_INVITATION_ACCEPTED',
+  SPACE_ADMIN_ORGANIZATION_COMMUNITY_INVITATION_DECLINED = 'SPACE_ADMIN_ORGANIZATION_COMMUNITY_INVITATION_DECLINED',
+  SPACE_ADMIN_USER_COMMUNITY_INVITATION_ACCEPTED = 'SPACE_ADMIN_USER_COMMUNITY_INVITATION_ACCEPTED',
+  SPACE_ADMIN_USER_COMMUNITY_INVITATION_DECLINED = 'SPACE_ADMIN_USER_COMMUNITY_INVITATION_DECLINED',
   // space lead
   SPACE_LEAD_COMMUNICATION_MESSAGE = 'SPACE_LEAD_COMMUNICATION_MESSAGE',
   // space community

src/common/enums/role.set.invitation.result.notice.ts

@@ -0,0 +1,12 @@
+import { registerEnumType } from '@nestjs/graphql';
+
+// Optional, informational addendum to a RoleSetInvitationResult that
+// stayed a success (e.g. INVITED_TO_ROLE_SET) but has something the
+// caller should know without treating the invite as failed.
+export enum RoleSetInvitationResultNotice {
+  ORGANIZATION_HAS_NO_ADMINISTRATORS = 'organization-has-no-administrators',
+}
+
+registerEnumType(RoleSetInvitationResultNotice, {
+  name: 'RoleSetInvitationResultNotice',
+});

src/common/enums/role.set.invitation.result.type.ts

@@ -8,6 +8,8 @@ export enum RoleSetInvitationResultType {
   INVITATION_TO_PARENT_NOT_AUTHORIZED = 'invitation-to-parent-not-authorized',
   ALREADY_HAS_OPEN_APPLICATION = 'already-has-open-application',
   ALREADY_MEMBER_OF_ROLE_SET = 'already-member-of-role-set',
+  ORGANIZATION_NOT_ACCEPTING_INVITATIONS = 'organization-not-accepting-invitations',
+  ORGANIZATION_LEAD_ROLE_LIMIT_REACHED = 'organization-lead-role-limit-reached',
 }
 
 registerEnumType(RoleSetInvitationResultType, {

src/config/organization-invitation-notifications.config.spec.ts

@@ -0,0 +1,54 @@
+/**
+ * Asserts the in-code default for the organization-invitation support
+ * escalation address resolves correctly when the corresponding env var is
+ * absent, and that it is env-overridable.
+ */
+
+const ORGANIZATION_INVITATION_ENV_VARS = [
+  'NOTIFICATIONS_ORGANIZATION_INVITATION_SUPPORT_EMAIL',
+] as const;
+
+describe('organization-invitation notifications configuration defaults', () => {
+  const origEnv: Record<string, string | undefined> = {};
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    for (const key of ORGANIZATION_INVITATION_ENV_VARS) {
+      origEnv[key] = process.env[key];
+      delete process.env[key];
+    }
+    origEnv.ALKEMIO_CONFIG_PATH = process.env.ALKEMIO_CONFIG_PATH;
+    delete process.env.ALKEMIO_CONFIG_PATH;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    for (const [key, val] of Object.entries(origEnv)) {
+      if (val === undefined) delete process.env[key];
+      else process.env[key] = val;
+    }
+  });
+
+  async function loadConfiguration() {
+    const mod = await import('./configuration');
+    return mod.default;
+  }
+
+  it('defaults support_email to support@alkem.io when the env var is absent', async () => {
+    const factory = await loadConfiguration();
+    const result = factory();
+    expect(result.notifications.organization_invitations.support_email).toBe(
+      'support@alkem.io'
+    );
+  });
+
+  it('support_email is env-overridable', async () => {
+    process.env.NOTIFICATIONS_ORGANIZATION_INVITATION_SUPPORT_EMAIL =
+      'escalations@example.com';
+    const factory = await loadConfiguration();
+    const result = factory();
+    expect(result.notifications.organization_invitations.support_email).toBe(
+      'escalations@example.com'
+    );
+  });
+});