accountsConfig:
  # The name of the ACL variable for the active team (@team), of the team key in the
  # POST /auth/switch-team response, and of the claim when "@team" is listed in
  # jwtConfigProvider/account-properties-claims. Default: "team".
  team-claim-name: team

  # Role name assigned to regular (non-admin) team members.
  # Default: "member". Set to "user" if your existing ACL rules use that label.
  member-role-name: member

  # Set to false to disable the built-in membership management endpoints:
  #   POST   /auth/invite
  #   POST   /auth/resend-invite
  #   GET    /auth/teams          POST   /auth/teams
  #   POST   /auth/switch-team
  #   GET    /auth/team/members
  #   PATCH  /auth/team           DELETE /auth/team
  # Useful when your custom provider exposes its own equivalent endpoints.
  # Default: true
  membership-endpoints-enabled: true

// package org.restheart.plugins.accounts  (in restheart-commons)

/**
 * Called when an OAuth-authenticated user has status "invited".
 * Return a non-empty Optional to activate the user and issue a JWT.
 * Return Optional.empty() to fall back to the default behaviour
 * (JWT with status:"invited" — blocked by ACL rules).
 */
default Optional<Membership> activateViaOAuth(String userId, ConsentRecord consents) {
    return Optional.empty(); // deny by default (preserves 9.4.1 behaviour)
}

// package org.restheart.plugins.accounts  (in restheart-commons)
public record ConsentRecord(String termsVersion, String privacyVersion,
                             String ip, Instant acceptedAt) {}

// package org.restheart.plugins.accounts  (in restheart-commons)

public interface MembershipProvider {

    /**
     * Creates an initial team for a newly registered user and assigns them
     * the owner role. Called during /auth/register and the OAuth new-user path.
     *
     * The user document already exists when this is called.
     * The returned TeamRef is what @team resolves to while this team is the active one.
     */
    TeamRef createInitialTeam(String userId, String teamName);

    /**
     * Returns true if the user is already a member of the given team.
     * Used by /auth/invite to prevent duplicate memberships.
     */
    boolean isMember(String userId, BsonValue teamId);

    /**
     * Adds a user to a team with the specified role (idempotent).
     * If the user has no active team yet, this should also set it.
     */
    void addMember(String userId, BsonValue teamId, String role);

    /**
     * Returns the user's currently active membership, or empty if none.
     * Consumed by every JWT issuance path.
     */
    Optional<Membership> activeMembership(String userId);

    /**
     * Returns all memberships for the user.
     * Used by GET /auth/teams.
     */
    List<Membership> listMemberships(String userId);

    /**
     * Sets the given team as the user's active membership.
     * Used by POST /auth/switch-team.
     * Must throw IllegalArgumentException if the user is not a member.
     */
    void setActiveMembership(String userId, BsonValue teamId);

    /**
     * Removes a user from the given team.
     * Called by DELETE /auth/remove-member.
     * Must remove the entry from both the user-side and the team-side store.
     * If the team was the user's active team, the active-team field must be cleared.
     * No-op if the user is not a member.
     * Default: throws UnsupportedOperationException.
     */
    default void removeMember(String userId, BsonValue teamId) {
        throw new UnsupportedOperationException("removeMember not implemented by this provider");
    }

    /**
     * Updates the org-level role of a member within the given team.
     * Called by PATCH /auth/member-role.
     * Must update the role on both the user-side and the team-side store.
     * No-op if the user is not a member.
     * Default: throws UnsupportedOperationException.
     */
    default void updateMemberRole(String userId, BsonValue teamId, String newRole) {
        throw new UnsupportedOperationException("updateMemberRole not implemented by this provider");
    }

    /**
     * Called when an OAuth-authenticated user has status "invited".
     * Return Optional.empty() to deny (default, preserves 9.4.1 behaviour).
     */
    default Optional<Membership> activateViaOAuth(String userId, ConsentRecord consents) {
        return Optional.empty();
    }

    /**
     * Returns the members of the given team with display information denormalized
     * from each member's user document. Called by GET /auth/team/members.
     * Default: throws UnsupportedOperationException.
     */
    default List<TeamMember> listTeamMembers(BsonValue teamId) {
        throw new UnsupportedOperationException("listTeamMembers not implemented by this provider");
    }

    /**
     * Creates an additional team for an already-registered user, assigns them
     * the owner role, and sets it as their newly active membership. Unlike
     * createInitialTeam, this may be called any number of times for the same
     * user. Called by POST /auth/teams.
     * Default: throws UnsupportedOperationException.
     */
    default TeamRef createTeam(String userId, String teamName) {
        throw new UnsupportedOperationException("createTeam not implemented by this provider");
    }

    /**
     * Updates a team's own fields (name and/or description, partial update —
     * either parameter may be null to leave that field unchanged).
     * Called by PATCH /auth/team.
     * Default: throws UnsupportedOperationException.
     */
    default void updateTeam(BsonValue teamId, String name, String description) {
        throw new UnsupportedOperationException("updateTeam not implemented by this provider");
    }

    /**
     * Deletes a team, but only if it has no other members — implementations
     * must enforce this atomically, server-side (a client-side pre-check is a
     * race condition against a concurrent invite acceptance). On success, also
     * clears the caller's own membership entry and active-team pointer.
     * Called by DELETE /auth/team.
     * Returns false (does not throw) if the team still has other members, or
     * no longer exists.
     * Default: throws UnsupportedOperationException.
     */
    default boolean deleteTeam(String userId, BsonValue teamId) {
        throw new UnsupportedOperationException("deleteTeam not implemented by this provider");
    }
}

// Tenant reference returned by createInitialTeam/createTeam — id is the native BsonValue
public record TeamRef(BsonValue id, String displayName) {}

// Snapshot of a single membership — teamId is the native BsonValue
public record Membership(BsonValue teamId, String displayName, String role, boolean active) {}

// A team member with display info denormalized from their user document,
// returned by listTeamMembers — email is the member's identifier
public record TeamMember(String email, String name, String role, Instant joinedAt) {}

// teams collection — created by createInitialTeam / createTeam, written by addMember, removeMember, updateMemberRole
{
  "_id":       { "$oid": "64a1b2c3d4e5f6a7b8c9d0e1" },
  "name":      "Acme Corp",
  "createdBy": "alice@example.com",
  "createdAt": { "$date": "…" },
  "members":   [{ "userId": "alice@example.com", "role": "owner", "joinedAt": { "$date": "…" } }]
}

// users collection — only the active team
{
  "_id":  "alice@example.com",
  "team": { "_id": { "$oid": "64a1b2c3d4e5f6a7b8c9d0e1" } }
}