fix(organizations): preserve member administration compatibility

Author: waleedlatif1

apps/docs/openapi-v2-resources.json

@@ -6376,7 +6376,7 @@
       "post": {
         "operationId": "createOrganizationInvitation",
         "summary": "Create Organization Invitation",
-        "description": "Email an invitation to join the organization as a member or administrator. Requires organization administrator access, invitations enabled, and an available seat on an eligible plan. This grants no workspace-specific permissions. A unexpired pending invitation for the email conflicts; use Resend Organization Invitation to send it again. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "description": "Email an invitation to join the organization as a member or administrator. Requires organization administrator access, invitations enabled, and an available seat on an eligible plan. This grants no workspace-specific permissions. An unexpired pending invitation for the email conflicts; use Resend Organization Invitation to send it again. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "organizations.invitations.create",
         "x-oauth-scope": "api:write",
         "tags": ["Organizations"],
@@ -6539,7 +6539,7 @@
       "delete": {
         "operationId": "revokeOrganizationInvitation",
         "summary": "Revoke Organization Invitation",
-        "description": "Cancel a unexpired pending invitation and all its workspace grants so it can no longer be accepted. Requires organization administrator access. This does not remove a person who already accepted; use Remove Organization Member for that. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "description": "Cancel an unexpired pending invitation and all its workspace grants so it can no longer be accepted. Requires organization administrator access. This does not remove a person who already accepted; use Remove Organization Member for that. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "invitations.revoke",
         "x-oauth-scope": "api:write",
         "tags": ["Organizations"],
@@ -6620,7 +6620,7 @@
       "post": {
         "operationId": "resendOrganizationInvitation",
         "summary": "Resend Organization Invitation",
-        "description": "Email a unexpired pending invitation again, renew its expiry, and replace its previous acceptance link. Requires organization administrator access and current invitation eligibility. Retrying sends another email; inspect the invitation after a delivery failure before retrying. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "description": "Email an unexpired pending invitation again, renew its expiry, and replace its previous acceptance link. Requires organization administrator access and current invitation eligibility. Retrying sends another email; inspect the invitation after a delivery failure before retrying. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "invitations.resend",
         "x-oauth-scope": "api:write",
         "tags": ["Organizations"],
@@ -14842,7 +14842,7 @@
           },
           "slug": {
             "type": "string",
-            "description": "Organization slug, or null when unset."
+            "description": "Organization slug."
           },
           "logo": {
             "anyOf": [

apps/sim/lib/api/contracts/v2/openapi/organizations.ts

@@ -316,7 +316,7 @@ export const organizationOpenApiRoutes = [
       applicationOperation: organizationOperations.createInvitation,
       operationId: 'createOrganizationInvitation',
       summary: 'Create Organization Invitation',
-      description: `Email an invitation to join the organization as a member or administrator. Requires organization administrator access, invitations enabled, and an available seat on an eligible plan. This grants no workspace-specific permissions. A unexpired pending invitation for the email conflicts; use Resend Organization Invitation to send it again. ${WORKSPACE_API_KEY_DENIED}`,
+      description: `Email an invitation to join the organization as a member or administrator. Requires organization administrator access, invitations enabled, and an available seat on an eligible plan. This grants no workspace-specific permissions. An unexpired pending invitation for the email conflicts; use Resend Organization Invitation to send it again. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
@@ -410,7 +410,7 @@ export const organizationOpenApiRoutes = [
       applicationOperation: invitationOperations.resend,
       operationId: 'resendOrganizationInvitation',
       summary: 'Resend Organization Invitation',
-      description: `Email a unexpired pending invitation again, renew its expiry, and replace its previous acceptance link. Requires organization administrator access and current invitation eligibility. Retrying sends another email; inspect the invitation after a delivery failure before retrying. ${WORKSPACE_API_KEY_DENIED}`,
+      description: `Email an unexpired pending invitation again, renew its expiry, and replace its previous acceptance link. Requires organization administrator access and current invitation eligibility. Retrying sends another email; inspect the invitation after a delivery failure before retrying. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
@@ -462,7 +462,7 @@ export const organizationOpenApiRoutes = [
       applicationOperation: invitationOperations.revoke,
       operationId: 'revokeOrganizationInvitation',
       summary: 'Revoke Organization Invitation',
-      description: `Cancel a unexpired pending invitation and all its workspace grants so it can no longer be accepted. Requires organization administrator access. This does not remove a person who already accepted; use Remove Organization Member for that. ${WORKSPACE_API_KEY_DENIED}`,
+      description: `Cancel an unexpired pending invitation and all its workspace grants so it can no longer be accepted. Requires organization administrator access. This does not remove a person who already accepted; use Remove Organization Member for that. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {

apps/sim/lib/api/contracts/v2/organizations.ts

@@ -34,7 +34,7 @@ export const v2OrganizationSchema = z
   .object({
     id: z.string().describe('Organization identifier.'),
     name: z.string().describe('Organization display name.'),
-    slug: z.string().describe('Organization slug, or null when unset.'),
+    slug: z.string().describe('Organization slug.'),
     logo: z.string().nullable().describe('Organization logo URL, or null when unset.'),
     role: organizationRoleSchema.describe('The acting user’s role in this organization.'),
     createdAt: v2TimestampSchema.describe('When the organization was created.'),

apps/sim/lib/api/mcp/generated/v2-operations.ts

@@ -653,7 +653,7 @@ export const V2_MCP_OPERATIONS = {
     contract: v2CreateOrganizationInvitationContract,
     summary: 'Create Organization Invitation',
     description:
-      'Email an invitation to join the organization as a member or administrator. Requires organization administrator access, invitations enabled, and an available seat on an eligible plan. This grants no workspace-specific permissions. A unexpired pending invitation for the email conflicts; use Resend Organization Invitation to send it again. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Email an invitation to join the organization as a member or administrator. Requires organization administrator access, invitations enabled, and an available seat on an eligible plan. This grants no workspace-specific permissions. An unexpired pending invitation for the email conflicts; use Resend Organization Invitation to send it again. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/invitations/route').then(
@@ -2070,7 +2070,7 @@ export const V2_MCP_OPERATIONS = {
     contract: v2ResendOrganizationInvitationContract,
     summary: 'Resend Organization Invitation',
     description:
-      'Email a unexpired pending invitation again, renew its expiry, and replace its previous acceptance link. Requires organization administrator access and current invitation eligibility. Retrying sends another email; inspect the invitation after a delivery failure before retrying. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Email an unexpired pending invitation again, renew its expiry, and replace its previous acceptance link. Requires organization administrator access and current invitation eligibility. Retrying sends another email; inspect the invitation after a delivery failure before retrying. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import(
@@ -2157,7 +2157,7 @@ export const V2_MCP_OPERATIONS = {
     contract: v2RevokeOrganizationInvitationContract,
     summary: 'Revoke Organization Invitation',
     description:
-      'Cancel a unexpired pending invitation and all its workspace grants so it can no longer be accepted. Requires organization administrator access. This does not remove a person who already accepted; use Remove Organization Member for that. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Cancel an unexpired pending invitation and all its workspace grants so it can no longer be accepted. Requires organization administrator access. This does not remove a person who already accepted; use Remove Organization Member for that. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/invitations/[invitationId]/route').then(

apps/sim/lib/billing/organizations/membership-external-removal.test.ts

@@ -4,6 +4,7 @@
 import { credential, knowledgeBase, member, workspaceFiles } from '@sim/db/schema'
 import { dbChainMockFns, hasMockCondition, queueTableRows, resetDbChainMock } from '@sim/testing'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { OrchestrationError } from '@/lib/core/orchestration/types'
 
 const { mockSetOrgMemberUsageLimit } = vi.hoisted(() => ({
   mockSetOrgMemberUsageLimit: vi.fn(),
@@ -102,11 +103,34 @@ describe('external organization access removal', () => {
           organizationId: 'org-1',
           userId: 'target',
           memberId: 'membership',
+          onError: 'throw',
         })
       ).rejects.toBe(failure)
     }
   )
 
+  it.each([
+    Object.assign(new Error('retry transaction'), { code: '40001' }),
+    Object.assign(new Error('retry transaction'), { code: '40P01' }),
+    Object.assign(new Error('retry transaction'), { code: '55P03' }),
+    new OrchestrationError('conflict', 'The membership changed before removal'),
+  ])('preserves failure results for legacy compound callers on $code', async (failure) => {
+    queueTableRows(member, [{ id: 'membership', userId: 'target', role: 'member' }])
+    dbChainMockFns.transaction.mockRejectedValueOnce(failure)
+
+    await expect(
+      removeUserFromOrganization({
+        organizationId: 'org-1',
+        userId: 'target',
+        memberId: 'membership',
+      })
+    ).resolves.toMatchObject({
+      success: false,
+      error: 'Failed to remove user from organization',
+    })
+    expect(dbChainMockFns.delete).not.toHaveBeenCalled()
+  })
+
   it('rejects an actor demoted before the locked removal', async () => {
     queueTableRows(member, [{ id: 'membership', userId: 'target', role: 'member' }])
     queueTableRows(member, [{ id: 'actor-membership', role: 'member' }])
@@ -116,6 +140,7 @@ describe('external organization access removal', () => {
         userId: 'target',
         memberId: 'membership',
         actorUserId: 'actor',
+        onError: 'throw',
       })
     ).rejects.toMatchObject({ code: 'forbidden' })
     expect(dbChainMockFns.delete).not.toHaveBeenCalled()

apps/sim/lib/billing/organizations/membership.ts

@@ -488,6 +488,8 @@ export interface RemoveMemberParams {
   spareSessionId?: string
   /** Acting member whose management authority is rechecked under the mutation lock. */
   actorUserId?: string
+  /** Legacy compound callers consume failure results; application use cases propagate errors. */
+  onError?: 'return-failure' | 'throw'
   /**
    * Only remove the member when they hold no remaining permission on any of the
    * org's workspaces, evaluated atomically under the membership lock. Used by
@@ -1288,6 +1290,7 @@ export async function removeUserFromOrganization(
     spareSessionToken,
     spareSessionId,
     actorUserId,
+    onError = 'return-failure',
   } = params
 
   const billingActions = {
@@ -1529,10 +1532,10 @@ export async function removeUserFromOrganization(
 
     return { success: true, removed: true, billingActions }
   } catch (error) {
-    if (error instanceof OrchestrationError || isRetryableTransactionError(error)) throw error
     if (error instanceof WorkspaceBillingAccountRemovalError) {
       return { success: false, error: error.message, billingActions }
     }
+    if (onError === 'throw') throw error
 
     logger.error('Failed to remove user from organization', {
       userId,

apps/sim/lib/organizations/application/members.ts

@@ -20,23 +20,18 @@ export const updateOrganizationMember = defineAuthorizedOrganizationUseCase({
     input: { organizationId: string; userId: string; role: 'member' | 'admin' | 'owner' }
     context: { userId: string }
   }) => updateOrganizationMemberRecord({ ...input, actorUserId: context.userId }),
-  projectAudit: ({ input, result }) =>
-    result.changed
-      ? [
-          {
-            action: AuditAction.ORG_MEMBER_ROLE_CHANGED,
-            resourceType: AuditResourceType.ORGANIZATION,
-            resourceId: input.organizationId,
-            description: `Changed role for member ${input.userId} to ${input.role}`,
-            metadata: {
-              targetUserId: input.userId,
-              targetEmail: result.member.userEmail,
-              targetName: result.member.userName,
-              changes: [{ field: 'role', from: result.previousRole, to: input.role }],
-            },
-          },
-        ]
-      : [],
+  projectAudit: ({ input, result }) => ({
+    action: AuditAction.ORG_MEMBER_ROLE_CHANGED,
+    resourceType: AuditResourceType.ORGANIZATION,
+    resourceId: input.organizationId,
+    description: `Changed role for member ${input.userId} to ${input.role}`,
+    metadata: {
+      targetUserId: input.userId,
+      targetEmail: result.member.userEmail,
+      targetName: result.member.userName,
+      changes: [{ field: 'role', from: result.previousRole, to: input.role }],
+    },
+  }),
 })
 
 export const removeOrganizationMember = defineAuthorizedOrganizationUseCase({

apps/sim/lib/organizations/application/use-cases.test.ts

@@ -161,10 +161,26 @@ describe('organization application operations', () => {
     expect(dbChainMockFns.select).not.toHaveBeenCalled()
   })
 
-  it('does not audit an unchanged role or failed write', async () => {
+  it('preserves audit on a successful same-role request', async () => {
     queueTableRows(member, [{ role: 'admin' }])
-    mocks.update.mockResolvedValueOnce({ member: target, changed: false })
+    mocks.update.mockResolvedValueOnce({
+      member: { ...target, role: 'admin' },
+      previousRole: 'admin',
+      changed: false,
+    })
     await updateOrganizationMember.execute({ principal: session, input: roleInput })
+    expect(recordAudit).toHaveBeenCalledExactlyOnceWith(
+      expect.objectContaining({
+        actorId: 'actor',
+        resourceId: 'org',
+        metadata: expect.objectContaining({
+          changes: [{ field: 'role', from: 'admin', to: 'admin' }],
+        }),
+      })
+    )
+  })
+
+  it('does not audit a failed role write', async () => {
     queueTableRows(member, [{ role: 'admin' }])
     mocks.update.mockRejectedValueOnce(new Error('database unavailable'))
     await expect(

apps/sim/lib/organizations/member-manager.test.ts

@@ -1,5 +1,5 @@
 /** @vitest-environment node */
-import { member } from '@sim/db/schema'
+import { member, user } from '@sim/db/schema'
 import { dbChainMockFns, queueTableRows, resetDbChainMock } from '@sim/testing'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
@@ -96,8 +96,21 @@ describe('organization member managers', () => {
       seatReduction: { changed: false },
     })
     expect(mocks.remove).toHaveBeenCalledWith(
-      expect.objectContaining({ actorUserId: 'actor', memberId: 'membership' })
+      expect.objectContaining({ actorUserId: 'actor', memberId: 'membership', onError: 'throw' })
     )
     expect(mocks.scim).not.toHaveBeenCalled()
   })
+
+  it('reports membership added before external-removal preflight as a conflict', async () => {
+    queueTableRows(member, [])
+    queueTableRows(user, [{ id: 'target', name: 'Person', email: 'person@example.com' }])
+    mocks.external.mockResolvedValue({ success: false, error: 'User is an organization member' })
+
+    await expect(removeOrganizationMemberRecord(input)).rejects.toMatchObject({
+      code: 'conflict',
+      message: 'User is an organization member',
+    })
+    expect(mocks.remove).not.toHaveBeenCalled()
+    expect(mocks.seats).not.toHaveBeenCalled()
+  })
 })

apps/sim/lib/organizations/member-manager.ts

@@ -72,9 +72,11 @@ export async function removeOrganizationMemberRecord(input: {
       const code =
         message === 'External workspace member not found'
           ? 'not_found'
-          : message === WORKSPACE_BILLING_ACCOUNT_REMOVAL_ERROR
-            ? 'validation'
-            : 'internal'
+          : message === 'User is an organization member'
+            ? 'conflict'
+            : message === WORKSPACE_BILLING_ACCOUNT_REMOVAL_ERROR
+              ? 'validation'
+              : 'internal'
       throw new OrchestrationError(code, message)
     }
     return {
@@ -84,7 +86,11 @@ export async function removeOrganizationMemberRecord(input: {
       seatReduction: null,
     }
   }
-  const removal = await removeUserFromOrganization({ ...input, memberId: target.id })
+  const removal = await removeUserFromOrganization({
+    ...input,
+    memberId: target.id,
+    onError: 'throw',
+  })
   if (!removal.success) {
     const message = removal.error || 'Failed to remove user from organization'
     const code =