linked-roles

Discord Linked Roles OAuth2

A basic wrapper for the Discord Linked Roles OAuth2 API.

Installation

$ pip install -U linked-roles

FastAPI Example:

from fastapi import FastAPI
from fastapi.responses import RedirectResponse

import config
from linked_roles import LinkedRolesOAuth2, OAuth2Scopes, RoleConnection, UserNotFound

app = FastAPI(title='Linked Roles OAuth2')

client = LinkedRolesOAuth2(
    client_id=config.DISCORD_CLIENT_ID,
    client_secret=config.DISCORD_CLIENT_SECRET,
    redirect_uri=config.DISCORD_REDIRECT_URI,
    # token=config.DISCORD_TOKEN, # Optinal for Resgister
    scopes=(OAuth2Scopes.role_connection_write, OAuth2Scopes.identify),
    state=config.COOKIE_SECRET,
)

@app.on_event('startup')
async def startup():
    await client.start()

@app.on_event('shutdown')
async def shutdown():
    await client.close()

@app.get('/linked-role')
async def linked_roles():
    url = client.get_oauth_url()
    return RedirectResponse(url=url)

@app.get('/verified-role')
async def verified_role(code: str):

    # get token
    token = await client.get_access_token(code)

    # get user
    user = await client.fetch_user(token)

    if user is None:
        raise UserNotFound('User not found')

    role = await user.fetch_role_connection()
    
    if role is None:
        # set role connection
        role = RoleConnection(platform_name='VALORANT', platform_username=str(user))

        # add metadata
        role.add_metadata(key='matches', value=10)
        role.add_metadata(key='winrate', value=20)
        role.add_metadata(key='combat_score', value=30)

        # set role metadata
        await user.edit_role_connection(role)

    return 'Role metadata set successfully. Please check your Discord profile.'

Register Example:

import asyncio

import config
from linked_roles import RoleMetadataType, LinkedRolesOAuth2, RoleMetadataRecord


async def main():

    client = LinkedRolesOAuth2(client_id=config.DISCORD_CLIENT_ID, token=config.DISCORD_TOKEN)

    async with client:

        records = (
            RoleMetadataRecord(
                key='matches',
                name='Matches',
                type=2,
            ),
            RoleMetadataRecord(
                key='winrate',
                name='Win Rate',
                type=RoleMetadataType.interger_greater_than_or_equal,  # Union Between int and RoleMetadataType
            ),
            RoleMetadataRecord(
                key='combat_score',
                name='Combat Score',
                description='Combat score this season', # description is optional (default: '...')
                type=RoleMetadataType.interger_greater_than_or_equal,
            )
        )

        records = await client.register_role_metadata(records=records, force=True)
        print(records)


if __name__ == '__main__':
    asyncio.run(main())

Config Example:

DISCORD_TOKEN = '<your bot token>'
DISCORD_CLIENT_ID = '<your client id>'
DISCORD_CLIENT_SECRET = '<your client secret>'
DISCORD_REDIRECT_URI = 'http://localhost:8000/verified-role'  # example redirect uri
COOKIE_SECRET = '<your cookie secret>'

# cookie secret can be generated with:
import uuid
>> uuid.uuid4().hex

More Examples:

• fastapi more examples: examples/fastapi

TODO:

• more examples
• documentation
• database support (postgresql, sqlite, etc.) ?
• localizations support

Code Style Inspiration

• discord.py

License

licensed under the MIT license.