better_auth 0.3.0 → 0.5.0

data/lib/better_auth/plugins/organization.rb

@@ -156,7 +156,7 @@ module BetterAuth
     end
 
     def organization_create_endpoint(config)
-      Endpoint.new(path: "/organization/create", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/create", method: "POST", metadata: organization_openapi("createOrganization", "Create an organization", response: organization_ref_schema("Organization"))) do |ctx|
         body = normalize_hash(ctx.body)
         session = Routes.current_session(ctx, allow_nil: true)
         user = session ? session[:user] : ctx.context.internal_adapter.find_user_by_id(body[:user_id])
@@ -204,7 +204,8 @@ module BetterAuth
     end
 
     def organization_check_slug_endpoint
-      Endpoint.new(path: "/organization/check-slug", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/check-slug", method: "POST", metadata: organization_openapi("checkOrganizationSlug", "Check if an organization slug is available", response: OpenAPI.status_response_schema)) do |ctx|
+        Routes.request_only_session(ctx)
         slug = normalize_hash(ctx.body)[:slug].to_s
         if slug.empty? || organization_by_slug(ctx, slug)
           raise APIError.new("BAD_REQUEST", message: ORGANIZATION_ERROR_CODES.fetch("ORGANIZATION_SLUG_ALREADY_TAKEN"))
@@ -214,7 +215,7 @@ module BetterAuth
     end
 
     def organization_list_endpoint
-      Endpoint.new(path: "/organization/list", method: "GET") do |ctx|
+      Endpoint.new(path: "/organization/list", method: "GET", metadata: organization_openapi("listOrganizations", "List organizations", response: organization_array_schema("Organization"))) do |ctx|
         session = Routes.current_session(ctx)
         members = ctx.context.adapter.find_many(model: "member", where: [{field: "userId", value: session[:user]["id"]}])
         organizations = members.filter_map { |member| organization_by_id(ctx, member["organizationId"]) }
@@ -223,7 +224,7 @@ module BetterAuth
     end
 
     def organization_update_endpoint(config)
-      Endpoint.new(path: "/organization/update", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/update", method: "POST", metadata: organization_openapi("updateOrganization", "Update an organization", response: organization_ref_schema("Organization"))) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         id = body[:organization_id] || body[:organizationId]
@@ -248,7 +249,7 @@ module BetterAuth
     end
 
     def organization_delete_endpoint(config)
-      Endpoint.new(path: "/organization/delete", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/delete", method: "POST", metadata: organization_openapi("deleteOrganization", "Delete an organization", response: OpenAPI.status_response_schema)) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         organization = organization_by_id(ctx, body[:organization_id]) || organization_by_slug(ctx, body[:organization_slug])
@@ -269,9 +270,15 @@ module BetterAuth
     end
 
     def organization_set_active_endpoint
-      Endpoint.new(path: "/organization/set-active", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/set-active", method: "POST", metadata: organization_openapi("setActiveOrganization", "Set the active organization", response: organization_nullable_schema("Organization"))) do |ctx|
         session = Routes.current_session(ctx, sensitive: true)
         body = normalize_hash(ctx.body)
+        if body.key?(:organization_id) && body[:organization_id].nil?
+          updated_session = ctx.context.internal_adapter.update_session(session[:session]["token"], {activeOrganizationId: nil, activeTeamId: nil})
+          Cookies.set_session_cookie(ctx, {session: updated_session || session[:session].merge("activeOrganizationId" => nil, "activeTeamId" => nil), user: session[:user]})
+          next ctx.json(nil)
+        end
+
         organization = organization_by_id(ctx, body[:organization_id]) || organization_by_slug(ctx, body[:organization_slug])
         raise APIError.new("BAD_REQUEST", message: ORGANIZATION_ERROR_CODES.fetch("ORGANIZATION_NOT_FOUND")) unless organization
         require_member!(ctx, session[:user]["id"], organization["id"])
@@ -282,14 +289,19 @@ module BetterAuth
     end
 
     def organization_get_full_endpoint(config)
-      Endpoint.new(path: "/organization/get-full-organization", method: "GET") do |ctx|
+      Endpoint.new(path: "/organization/get-full-organization", method: "GET", metadata: organization_openapi("getOrganization", "Get the full organization", response: organization_nullable_schema("Organization"))) do |ctx|
         session = Routes.current_session(ctx)
         query = normalize_hash(ctx.query)
+        explicit_lookup = query.key?(:organization_slug) || query.key?(:organization_id)
         organization = organization_by_slug(ctx, query[:organization_slug]) || organization_by_id(ctx, query[:organization_id] || session[:session]["activeOrganizationId"])
-        next ctx.json(nil) unless organization
+        unless organization
+          raise APIError.new("BAD_REQUEST", message: ORGANIZATION_ERROR_CODES.fetch("ORGANIZATION_NOT_FOUND")) if explicit_lookup
+
+          next ctx.json(nil)
+        end
 
         require_member!(ctx, session[:user]["id"], organization["id"])
-        members = list_members_for(ctx, organization["id"])
+        members = list_members_for(ctx, organization["id"], {limit: query[:members_limit] || config[:membership_limit]})
         invitations = ctx.context.adapter.find_many(model: "invitation", where: [{field: "organizationId", value: organization["id"]}])
         result = organization_wire(ctx, organization).merge(
           members: members.fetch(:members),
@@ -304,10 +316,10 @@ module BetterAuth
     end
 
     def organization_invite_endpoint(config)
-      Endpoint.new(path: "/organization/invite-member", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/invite-member", method: "POST", metadata: organization_openapi("createOrganizationInvitation", "Create an organization invitation", response: organization_ref_schema("Invitation"))) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
-        organization = organization_by_id(ctx, body[:organization_id])
+        organization = organization_by_id(ctx, body[:organization_id] || session[:session]["activeOrganizationId"]) || organization_by_slug(ctx, body[:organization_slug])
         raise APIError.new("BAD_REQUEST", message: ORGANIZATION_ERROR_CODES.fetch("ORGANIZATION_NOT_FOUND")) unless organization
         require_org_permission!(ctx, config, session, organization["id"], {invitation: ["create"]}, ORGANIZATION_ERROR_CODES.fetch("YOU_ARE_NOT_ALLOWED_TO_INVITE_USERS_TO_THIS_ORGANIZATION"))
         email = body[:email].to_s.downcase
@@ -334,27 +346,32 @@ module BetterAuth
           raise APIError.new("FORBIDDEN", message: ORGANIZATION_ERROR_CODES.fetch("INVITATION_LIMIT_REACHED"))
         end
         team_ids = organization_team_ids(body[:team_id] || body[:team_ids])
+        ensure_team_member_capacity!(ctx, config, team_ids)
+        invitation_data = {
+          organizationId: organization["id"],
+          email: email,
+          role: role,
+          status: "pending",
+          expiresAt: Time.now + config[:invitation_expires_in].to_i,
+          inviterId: session[:user]["id"],
+          teamId: team_ids.any? ? team_ids.join(",") : nil,
+          createdAt: Time.now
+        }.merge(additional_input(body, :organization_id, :organization_slug, :email, :role, :team_id, :team_ids))
+        merge_hook_data!(invitation_data, run_org_hook(config, :before_create_invitation, {invitation: invitation_data, inviter: session[:user], organization: organization_wire(ctx, organization)}, ctx))
         invitation = ctx.context.adapter.create(
           model: "invitation",
-          data: {
-            organizationId: organization["id"],
-            email: email,
-            role: role,
-            status: "pending",
-            expiresAt: Time.now + config[:invitation_expires_in].to_i,
-            inviterId: session[:user]["id"],
-            teamId: team_ids.any? ? team_ids.join(",") : nil,
-            createdAt: Time.now
-          }
+          data: invitation_data,
+          force_allow_id: true
         )
         sender = config[:send_invitation_email]
         sender.call({id: invitation["id"], role: role, email: email, organization: organization_wire(ctx, organization), invitation: invitation_wire(ctx, invitation), inviter: require_member!(ctx, session[:user]["id"], organization["id"])}, ctx.request) if sender.respond_to?(:call)
+        run_org_hook(config, :after_create_invitation, {invitation: invitation_wire(ctx, invitation), inviter: session[:user], organization: organization_wire(ctx, organization)}, ctx)
         ctx.json(invitation_wire(ctx, invitation))
       end
     end
 
     def organization_accept_invitation_endpoint(config)
-      Endpoint.new(path: "/organization/accept-invitation", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/accept-invitation", method: "POST", metadata: organization_openapi("acceptOrganizationInvitation", "Accept an organization invitation", response: organization_accept_invitation_schema)) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         invitation = invitation_by_id(ctx, body[:invitation_id] || body[:id])
@@ -365,6 +382,7 @@ module BetterAuth
         if config[:require_email_verification_on_invitation] && !session[:user]["emailVerified"]
           raise APIError.new("FORBIDDEN", message: ORGANIZATION_ERROR_CODES.fetch("EMAIL_VERIFICATION_REQUIRED_BEFORE_ACCEPTING_OR_REJECTING_INVITATION"))
         end
+        ensure_team_member_capacity!(ctx, config, organization_team_ids(invitation["teamId"]))
         member = ctx.context.adapter.create(model: "member", data: {organizationId: invitation["organizationId"], userId: session[:user]["id"], role: invitation["role"], createdAt: Time.now})
         organization_team_ids(invitation["teamId"]).each do |team_id|
           ctx.context.adapter.create(model: "teamMember", data: {teamId: team_id, userId: session[:user]["id"], createdAt: Time.now})
@@ -377,7 +395,7 @@ module BetterAuth
     end
 
     def organization_reject_invitation_endpoint(_config)
-      Endpoint.new(path: "/organization/reject-invitation", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/reject-invitation", method: "POST", metadata: organization_openapi("rejectOrganizationInvitation", "Reject an organization invitation", response: organization_ref_schema("Invitation"))) do |ctx|
         session = Routes.current_session(ctx)
         invitation = invitation_by_id(ctx, normalize_hash(ctx.body)[:invitation_id])
         raise APIError.new("BAD_REQUEST", message: ORGANIZATION_ERROR_CODES.fetch("INVITATION_NOT_FOUND")) unless invitation
@@ -388,7 +406,7 @@ module BetterAuth
     end
 
     def organization_cancel_invitation_endpoint(config)
-      Endpoint.new(path: "/organization/cancel-invitation", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/cancel-invitation", method: "POST", metadata: organization_openapi("cancelOrganizationInvitation", "Cancel an organization invitation", response: organization_ref_schema("Invitation"))) do |ctx|
         session = Routes.current_session(ctx)
         invitation = invitation_by_id(ctx, normalize_hash(ctx.body)[:invitation_id])
         raise APIError.new("BAD_REQUEST", message: ORGANIZATION_ERROR_CODES.fetch("INVITATION_NOT_FOUND")) unless invitation
@@ -399,7 +417,7 @@ module BetterAuth
     end
 
     def organization_get_invitation_endpoint
-      Endpoint.new(path: "/organization/get-invitation", method: "GET") do |ctx|
+      Endpoint.new(path: "/organization/get-invitation", method: "GET", metadata: organization_openapi("getOrganizationInvitation", "Get an organization invitation", response: organization_ref_schema("Invitation"))) do |ctx|
         invitation = invitation_by_id(ctx, normalize_hash(ctx.query)[:id] || normalize_hash(ctx.query)[:invitation_id])
         raise APIError.new("BAD_REQUEST", message: ORGANIZATION_ERROR_CODES.fetch("INVITATION_NOT_FOUND")) unless invitation
         ctx.json(invitation_wire(ctx, invitation))
@@ -407,7 +425,7 @@ module BetterAuth
     end
 
     def organization_list_invitations_endpoint(config)
-      Endpoint.new(path: "/organization/list-invitations", method: "GET") do |ctx|
+      Endpoint.new(path: "/organization/list-invitations", method: "GET", metadata: organization_openapi("listOrganizationInvitations", "List organization invitations", response: organization_array_schema("Invitation"))) do |ctx|
         session = Routes.current_session(ctx)
         organization_id = normalize_hash(ctx.query)[:organization_id] || session[:session]["activeOrganizationId"]
         raise APIError.new("BAD_REQUEST", message: ORGANIZATION_ERROR_CODES.fetch("NO_ACTIVE_ORGANIZATION")) unless organization_id
@@ -418,7 +436,7 @@ module BetterAuth
     end
 
     def organization_list_user_invitations_endpoint
-      Endpoint.new(path: "/organization/list-user-invitations", method: "GET") do |ctx|
+      Endpoint.new(path: "/organization/list-user-invitations", method: "GET", metadata: organization_openapi("listUserInvitations", "List user invitations", response: organization_array_schema("Invitation"))) do |ctx|
         session = Routes.current_session(ctx)
         invitations = ctx.context.adapter.find_many(model: "invitation", where: [{field: "email", value: session[:user]["email"].to_s.downcase}, {field: "status", value: "pending"}])
         ctx.json(invitations.map { |entry| invitation_wire(ctx, entry) })
@@ -426,7 +444,7 @@ module BetterAuth
     end
 
     def organization_add_member_endpoint(config)
-      Endpoint.new(path: "/organization/add-member", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/add-member", method: "POST", metadata: organization_openapi("addOrganizationMember", "Add an organization member", response: organization_ref_schema("Member"))) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         organization_id = body[:organization_id]
@@ -447,7 +465,7 @@ module BetterAuth
     end
 
     def organization_remove_member_endpoint(config)
-      Endpoint.new(path: "/organization/remove-member", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/remove-member", method: "POST", metadata: organization_openapi("removeOrganizationMember", "Remove an organization member", response: OpenAPI.status_response_schema)) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         member = member_by_id(ctx, body[:member_id]) || require_member(ctx, body[:user_id], body[:organization_id])
@@ -464,7 +482,7 @@ module BetterAuth
     end
 
     def organization_update_member_role_endpoint(config)
-      Endpoint.new(path: "/organization/update-member-role", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/update-member-role", method: "POST", metadata: organization_openapi("updateOrganizationMemberRole", "Update an organization member role", response: organization_ref_schema("Member"))) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         member = member_by_id(ctx, body[:member_id]) || require_member(ctx, body[:user_id], body[:organization_id])
@@ -476,7 +494,7 @@ module BetterAuth
     end
 
     def organization_get_active_member_endpoint(_config)
-      Endpoint.new(path: "/organization/get-active-member", method: "GET") do |ctx|
+      Endpoint.new(path: "/organization/get-active-member", method: "GET", metadata: organization_openapi("getActiveOrganizationMember", "Get the active organization member", response: organization_ref_schema("Member"))) do |ctx|
         session = Routes.current_session(ctx)
         organization_id = normalize_hash(ctx.query)[:organization_id] || session[:session]["activeOrganizationId"]
         raise APIError.new("BAD_REQUEST", message: ORGANIZATION_ERROR_CODES.fetch("NO_ACTIVE_ORGANIZATION")) unless organization_id
@@ -486,17 +504,19 @@ module BetterAuth
     end
 
     def organization_get_active_member_role_endpoint(_config)
-      Endpoint.new(path: "/organization/get-active-member-role", method: "GET") do |ctx|
+      Endpoint.new(path: "/organization/get-active-member-role", method: "GET", metadata: organization_openapi("getActiveOrganizationMemberRole", "Get the active organization member role", response: organization_active_member_role_schema)) do |ctx|
         session = Routes.current_session(ctx)
-        organization_id = normalize_hash(ctx.query)[:organization_id] || session[:session]["activeOrganizationId"]
+        query = normalize_hash(ctx.query)
+        organization_id = query[:organization_id] || session[:session]["activeOrganizationId"]
         raise APIError.new("BAD_REQUEST", message: ORGANIZATION_ERROR_CODES.fetch("NO_ACTIVE_ORGANIZATION")) unless organization_id
-        member = require_member!(ctx, session[:user]["id"], organization_id)
-        ctx.json({role: member["role"]})
+        require_member!(ctx, session[:user]["id"], organization_id)
+        member = require_member!(ctx, query[:user_id] || session[:user]["id"], organization_id)
+        ctx.json({role: member["role"], member: member_wire(ctx, member)})
       end
     end
 
     def organization_leave_endpoint(config)
-      Endpoint.new(path: "/organization/leave", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/leave", method: "POST", metadata: organization_openapi("leaveOrganization", "Leave an organization", response: OpenAPI.status_response_schema)) do |ctx|
         session = Routes.current_session(ctx)
         organization_id = normalize_hash(ctx.body)[:organization_id]
         member = require_member!(ctx, session[:user]["id"], organization_id)
@@ -508,10 +528,10 @@ module BetterAuth
     end
 
     def organization_list_members_endpoint(_config)
-      Endpoint.new(path: "/organization/list-members", method: "GET") do |ctx|
+      Endpoint.new(path: "/organization/list-members", method: "GET", metadata: organization_openapi("listOrganizationMembers", "List organization members", response: organization_members_response_schema)) do |ctx|
         session = Routes.current_session(ctx)
         query = normalize_hash(ctx.query)
-        organization_id = query[:organization_id] || organization_by_slug(ctx, query[:organization_slug])&.fetch("id")
+        organization_id = query[:organization_id] || organization_by_slug(ctx, query[:organization_slug])&.fetch("id") || session[:session]["activeOrganizationId"]
         raise APIError.new("BAD_REQUEST", message: ORGANIZATION_ERROR_CODES.fetch("NO_ACTIVE_ORGANIZATION")) unless organization_id
         require_member!(ctx, session[:user]["id"], organization_id)
         ctx.json(list_members_for(ctx, organization_id, query))
@@ -519,7 +539,7 @@ module BetterAuth
     end
 
     def organization_has_permission_endpoint(config)
-      Endpoint.new(path: "/organization/has-permission", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/has-permission", method: "POST", metadata: organization_openapi("hasOrganizationPermission", "Check if the member has organization permission", response: organization_permission_response_schema)) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         organization_id = body[:organization_id] || session[:session]["activeOrganizationId"]
@@ -531,7 +551,7 @@ module BetterAuth
     end
 
     def organization_create_team_endpoint(config)
-      Endpoint.new(path: "/organization/create-team", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/create-team", method: "POST", metadata: organization_openapi("createOrganizationTeam", "Create an organization team", response: organization_ref_schema("Team"))) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         organization_id = body[:organization_id] || session[:session]["activeOrganizationId"]
@@ -543,7 +563,7 @@ module BetterAuth
         end
         team_data = {organizationId: organization_id, name: body[:name].to_s, createdAt: Time.now}.merge(additional_input(body, :organization_id, :name))
         merge_hook_data!(team_data, run_org_hook(config, :before_create_team, {team: team_data, user: session[:user], organization: organization_wire(ctx, organization)}, ctx))
-        team = ctx.context.adapter.create(model: "team", data: team_data)
+        team = ctx.context.adapter.create(model: "team", data: team_data, force_allow_id: true)
         ctx.context.adapter.create(model: "teamMember", data: {teamId: team["id"], userId: session[:user]["id"], createdAt: Time.now})
         run_org_hook(config, :after_create_team, {team: team_wire(ctx, team), user: session[:user], organization: organization_wire(ctx, organization)}, ctx)
         ctx.json(team_wire(ctx, team))
@@ -551,7 +571,7 @@ module BetterAuth
     end
 
     def organization_list_teams_endpoint(_config)
-      Endpoint.new(path: "/organization/list-teams", method: "GET") do |ctx|
+      Endpoint.new(path: "/organization/list-teams", method: "GET", metadata: organization_openapi("listOrganizationTeams", "List organization teams", response: organization_array_schema("Team"))) do |ctx|
         session = Routes.current_session(ctx)
         organization_id = normalize_hash(ctx.query)[:organization_id] || session[:session]["activeOrganizationId"]
         require_member!(ctx, session[:user]["id"], organization_id)
@@ -561,7 +581,7 @@ module BetterAuth
     end
 
     def organization_update_team_endpoint(config)
-      Endpoint.new(path: "/organization/update-team", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/update-team", method: "POST", metadata: organization_openapi("updateOrganizationTeam", "Update an organization team", response: organization_ref_schema("Team"))) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         team = team_by_id(ctx, body[:team_id])
@@ -573,7 +593,7 @@ module BetterAuth
     end
 
     def organization_remove_team_endpoint(config)
-      Endpoint.new(path: "/organization/remove-team", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/remove-team", method: "POST", metadata: organization_openapi("removeOrganizationTeam", "Remove an organization team", response: OpenAPI.status_response_schema)) do |ctx|
         session = Routes.current_session(ctx)
         team = team_by_id(ctx, normalize_hash(ctx.body)[:team_id])
         raise APIError.new("BAD_REQUEST", message: ORGANIZATION_ERROR_CODES.fetch("TEAM_NOT_FOUND")) unless team
@@ -589,7 +609,7 @@ module BetterAuth
     end
 
     def organization_set_active_team_endpoint(_config)
-      Endpoint.new(path: "/organization/set-active-team", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/set-active-team", method: "POST", metadata: organization_openapi("setActiveOrganizationTeam", "Set the active organization team", response: organization_nullable_schema("Team"))) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         if body.key?(:team_id) && body[:team_id].nil?
@@ -607,7 +627,7 @@ module BetterAuth
     end
 
     def organization_list_user_teams_endpoint
-      Endpoint.new(path: "/organization/list-user-teams", method: "GET") do |ctx|
+      Endpoint.new(path: "/organization/list-user-teams", method: "GET", metadata: organization_openapi("listUserTeams", "List user teams", response: organization_array_schema("Team"))) do |ctx|
         session = Routes.current_session(ctx)
         memberships = ctx.context.adapter.find_many(model: "teamMember", where: [{field: "userId", value: session[:user]["id"]}])
         ctx.json(memberships.filter_map { |entry| team_by_id(ctx, entry["teamId"]) }.map { |team| team_wire(ctx, team) })
@@ -615,7 +635,7 @@ module BetterAuth
     end
 
     def organization_list_team_members_endpoint(_config)
-      Endpoint.new(path: "/organization/list-team-members", method: "GET") do |ctx|
+      Endpoint.new(path: "/organization/list-team-members", method: "GET", metadata: organization_openapi("listTeamMembers", "List team members", response: organization_array_schema("TeamMember"))) do |ctx|
         session = Routes.current_session(ctx)
         team_id = normalize_hash(ctx.query)[:team_id] || session[:session]["activeTeamId"]
         raise APIError.new("BAD_REQUEST", message: ORGANIZATION_ERROR_CODES.fetch("YOU_DO_NOT_HAVE_AN_ACTIVE_TEAM")) unless team_id
@@ -627,7 +647,7 @@ module BetterAuth
     end
 
     def organization_add_team_member_endpoint(config)
-      Endpoint.new(path: "/organization/add-team-member", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/add-team-member", method: "POST", metadata: organization_openapi("addTeamMember", "Add a team member", response: organization_ref_schema("TeamMember"))) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         team = team_by_id(ctx, body[:team_id])
@@ -648,7 +668,7 @@ module BetterAuth
     end
 
     def organization_remove_team_member_endpoint(config)
-      Endpoint.new(path: "/organization/remove-team-member", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/remove-team-member", method: "POST", metadata: organization_openapi("removeTeamMember", "Remove a team member", response: OpenAPI.status_response_schema)) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         team = team_by_id(ctx, body[:team_id])
@@ -660,7 +680,7 @@ module BetterAuth
     end
 
     def organization_create_role_endpoint(config)
-      Endpoint.new(path: "/organization/create-role", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/create-role", method: "POST", metadata: organization_openapi("createOrganizationRole", "Create an organization role", response: organization_role_action_schema)) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         organization_id = body[:organization_id] || session[:session]["activeOrganizationId"]
@@ -679,7 +699,7 @@ module BetterAuth
     end
 
     def organization_list_roles_endpoint(config)
-      Endpoint.new(path: "/organization/list-roles", method: "GET") do |ctx|
+      Endpoint.new(path: "/organization/list-roles", method: "GET", metadata: organization_openapi("listOrganizationRoles", "List organization roles", response: {type: "array", items: organization_role_schema})) do |ctx|
         session = Routes.current_session(ctx)
         organization_id = normalize_hash(ctx.query)[:organization_id] || session[:session]["activeOrganizationId"]
         require_org_permission!(ctx, config, session, organization_id, {ac: ["read"]}, ORGANIZATION_ERROR_CODES.fetch("YOU_ARE_NOT_ALLOWED_TO_LIST_A_ROLE"))
@@ -690,7 +710,7 @@ module BetterAuth
     end
 
     def organization_get_role_endpoint(config)
-      Endpoint.new(path: "/organization/get-role", method: "GET") do |ctx|
+      Endpoint.new(path: "/organization/get-role", method: "GET", metadata: organization_openapi("getOrganizationRole", "Get an organization role", response: organization_role_schema)) do |ctx|
         session = Routes.current_session(ctx)
         query = normalize_hash(ctx.query)
         organization_id = query[:organization_id] || session[:session]["activeOrganizationId"]
@@ -702,7 +722,7 @@ module BetterAuth
     end
 
     def organization_update_role_endpoint(config)
-      Endpoint.new(path: "/organization/update-role", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/update-role", method: "POST", metadata: organization_openapi("updateOrganizationRole", "Update an organization role", response: organization_role_action_schema)) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         organization_id = body[:organization_id] || session[:session]["activeOrganizationId"]
@@ -727,7 +747,7 @@ module BetterAuth
     end
 
     def organization_delete_role_endpoint(config)
-      Endpoint.new(path: "/organization/delete-role", method: "POST") do |ctx|
+      Endpoint.new(path: "/organization/delete-role", method: "POST", metadata: organization_openapi("deleteOrganizationRole", "Delete an organization role", response: OpenAPI.success_response_schema)) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         organization_id = body[:organization_id] || session[:session]["activeOrganizationId"]
@@ -747,6 +767,104 @@ module BetterAuth
       end
     end
 
+    def organization_openapi(operation_id, description, response:, response_description: "Success", request: nil, required: [], parameters: nil)
+      openapi = {
+        operationId: operation_id,
+        description: description,
+        responses: {
+          "200" => OpenAPI.json_response(response_description, response)
+        }
+      }
+      openapi[:requestBody] = OpenAPI.json_request_body(OpenAPI.object_schema(request, required: required)) if request
+      openapi[:parameters] = parameters if parameters
+
+      {openapi: openapi}
+    end
+
+    def organization_ref_schema(name)
+      {
+        type: "object",
+        "$ref": "#/components/schemas/#{name}"
+      }
+    end
+
+    def organization_nullable_schema(name)
+      {
+        type: ["object", "null"],
+        "$ref": "#/components/schemas/#{name}"
+      }
+    end
+
+    def organization_array_schema(name)
+      {
+        type: "array",
+        items: organization_ref_schema(name)
+      }
+    end
+
+    def organization_accept_invitation_schema
+      OpenAPI.object_schema(
+        {
+          invitation: organization_ref_schema("Invitation"),
+          member: organization_ref_schema("Member")
+        },
+        required: ["invitation", "member"]
+      )
+    end
+
+    def organization_active_member_role_schema
+      OpenAPI.object_schema(
+        {
+          role: {type: "string"},
+          member: organization_ref_schema("Member")
+        },
+        required: ["role", "member"]
+      )
+    end
+
+    def organization_members_response_schema
+      OpenAPI.object_schema(
+        {
+          members: organization_array_schema("Member"),
+          total: {type: "number"}
+        },
+        required: ["members", "total"]
+      )
+    end
+
+    def organization_permission_response_schema
+      OpenAPI.object_schema(
+        {
+          error: {type: ["string", "null"]},
+          success: {type: "boolean"}
+        },
+        required: ["success"]
+      )
+    end
+
+    def organization_role_schema
+      OpenAPI.object_schema(
+        {
+          id: {type: "string"},
+          organizationId: {type: "string"},
+          role: {type: "string"},
+          permission: {type: "object"}
+        },
+        required: ["role", "permission"]
+      )
+    end
+
+    def organization_role_action_schema
+      OpenAPI.object_schema(
+        {
+          success: {type: "boolean"},
+          roleData: organization_role_schema,
+          statements: {type: "object"}
+        },
+        required: ["success", "roleData"]
+      )
+    end
+
     def parse_roles(roles)
       Array(roles).join(",")
     end
@@ -864,7 +982,7 @@ module BetterAuth
         where: where,
         limit: query[:limit],
         offset: query[:offset],
-        sort_by: query[:sort_by] ? {field: query[:sort_by], direction: query[:sort_order] || "asc"} : nil
+        sort_by: query[:sort_by] ? {field: query[:sort_by], direction: query[:sort_direction] || query[:sort_order] || "asc"} : nil
       )
       {
         members: members.map { |entry| member_wire(ctx, entry) },
@@ -872,6 +990,18 @@ module BetterAuth
       }
     end
 
+    def ensure_team_member_capacity!(ctx, config, team_ids)
+      max_members = config.dig(:teams, :maximum_members_per_team)
+      return unless max_members && team_ids.any?
+
+      team_ids.each do |team_id|
+        count = ctx.context.adapter.count(model: "teamMember", where: [{field: "teamId", value: team_id}])
+        if count >= max_members.to_i
+          raise APIError.new("FORBIDDEN", message: ORGANIZATION_ERROR_CODES.fetch("TEAM_MEMBER_LIMIT_REACHED"))
+        end
+      end
+    end
+
     def member_wire(ctx, member)
       data = Schema.parse_output(ctx.context.options, "member", member)
       user = ctx.context.internal_adapter.find_user_by_id(member["userId"])
@@ -915,7 +1045,7 @@ module BetterAuth
       team = if custom.respond_to?(:call)
         custom.call(organization_wire(ctx, organization), ctx)
       else
-        ctx.context.adapter.create(model: "team", data: team_data)
+        ctx.context.adapter.create(model: "team", data: team_data, force_allow_id: true)
       end
       ctx.context.adapter.create(model: "teamMember", data: {teamId: team["id"], userId: session[:user]["id"], createdAt: Time.now})
       run_org_hook(config, :after_create_team, {team: team_wire(ctx, team), user: session[:user], organization: organization_wire(ctx, organization)}, ctx)