# Collaborators

Greenruhm supports the addition of any number of credited collaborators on a drop using the asynchronous `drop.addCollaborator()` method.\
\
The collaborator must approve the invite to be added to the drop. Until they approve, they are a pending collaborator. If they reject the invite, we remove them from the drop and notify the drop creator that the invitation was rejected.

### There are two options for adding a collaborator:

1. The collaborator already has a Greenruhm account.
2. The collaborator does not have a Greenruhm account.

#### To add a collaborator using a username:

1. The user provides the Greenruhm username of the person they want to add.
2. We check if the username exists.
3. If it exists, we fetch the user's data and add them as a collaborator.
4. If the username does not exist, we inform the user that the provided username does not exist.

#### To add a collaborator using an email:

1. The user provides the email of the person they want to add.
2. We check if the email is in use by a Greenruhm user.
3. If it is, we fetch the user's data and add them as a collaborator.
4. If it is not, we send an invite to create an account to the email and add them as a collaborator.
5. If the email is invalid or not in a proper format, we inform the user that the provided email is invalid.

### Signature

```javascript
drop.addCollaborator({
  email: String = '',
  username: String = '',
  roles: [...String] = []
  displayCredits: String = ''
}) => Promise(PendingCollaborator)
```

### Collaborator Data Types

```graphql
type NewUserCollaboratorInvite {
  email: String!
  roles: [String!]!
  displayCredits: String
  isPending: Boolean!
}

type Collaborator {
  username: String!
  roles: [String!]!
  displayCredits: String
  isPending: Boolean!
}

union PendingCollaborator = NewUserCollaboratorInvite | Collaborator
```

* `email` - An email for the invited collaborator. (Optional. Only for new users)
* `username` - A valid Greenruhm username. (Optional. Only for existing users)
* `roles` - An array of strings, which SHOULD be DDEX roles. (Optional. Defaults to empty array)
* `displayCredits` - How credits should be listed in liner notes. (Optional)
* `isPending` - Newly added collaborators are **pending** until they accept the invitation. (Not a parameter. Managed automatically by Greenruhm Connect)

### Usage

```javascript
drop.addCollaborator({
  username: "stevie",
  roles: ["Musician", "Composer", "LeadVocals", "Drums", "Keyboards"],
  displayCredits: "Stevie: Pretty much everything."
})
```

### Roles

The `role` field is an array. A single collaborator can have several roles. Please use standard DDEX role names where available, but it is also OK to create custom roles. The following is a list of common roles:

* `MainArtist`
* `DisplayArtist`
* `FeaturedArtist`
* `Musician`
* `Vocalist`
* `LeadVocalist`
* `BackgroundVocalist`
* `Lyricist`
* `Composer`
* `ComposerLyricist`
* `ComposerAndOrLyricist`
* `Guitar`
* `Drums`
* `Voice`
* `Bass`
* `SoundDesigner`
* `Producer`
* `VisualDesigner`
* `Illustrator`
* `MotionDesigner`
* `Animator`
* `3D`
* `SoftwareDeveloper`

On Greenruhm, the drop creator gets a `DisplayArtist` role by default.

### Removing Collaborators

Use the asynchronous `drop.removeCollaborator()` method to remove a collaborator from a drop. This method can only be used before the drop is published.

```javascript
drop.removeCollaborator(usernameOrEmail: String) => Promise
```

To remove a collaborator:

```javascript
drop.removeCollaborator('stevie');
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://connect.greenruhm.com/fundamentals/collaborators.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.