Users Service

Manage users within a company, including their experience points, assets, notes, and quickrolls. This service provides comprehensive user management for World of Darkness campaigns.

Usage

from vclient import users_service

users = users_service(company_id="COMPANY_ID")

Methods

CRUD Operations

Method	Returns	Description
`get(user_id)`	`User`	Retrieve a user by ID
`create(request=None, **kwargs)`	`User`	Create a new user
`register(request=None, **kwargs)`	`User`	Register via SSO
`update(user_id, request=None, **kwargs)`	`User`	Update user properties
`delete(user_id, requesting_user_id)`	`None`	Delete a user

Pagination Methods

Method	Returns	Description
`get_page(user_role=None, limit=10, offset=0)`	`PaginatedResponse[User]`	Retrieve a paginated page
`list_all(user_role=None)`	`list[User]`	Retrieve all users
`iter_all(user_role=None, limit=100)`	`AsyncIterator[User]`	Iterate through all users

User Approval

Method	Returns	Description
`get_unapproved_page(limit=10, offset=0)`	`PaginatedResponse[User]`	List unapproved users (paginated)
`list_all_unapproved()`	`list[User]`	List all unapproved users
`iter_all_unapproved(limit=100)`	`AsyncIterator[User]`	Iterate through unapproved users
`approve_user(user_id, role, requesting_user_id)`	`User`	Approve a user and assign a role
`deny_user(user_id, requesting_user_id)`	`None`	Deny an unapproved user
`merge(primary_user_id, secondary_user_id, requesting_user_id)`	`User`	Merge unapproved user into primary

Statistics

Method	Returns	Description
`get_statistics(user_id, num_top_traits=5)`	`RollStatistics`	Retrieve aggregated roll stats

Experience Management

Method	Returns	Description
`get_experience(user_id, campaign_id)`	`CampaignExperience`	Retrieve XP and cool points
`add_xp(user_id, campaign_id, amount, requesting_user_id)`	`CampaignExperience`	Award experience points
`remove_xp(user_id, campaign_id, amount, requesting_user_id)`	`CampaignExperience`	Deduct experience points
`add_cool_points(user_id, campaign_id, amount, requesting_user_id)`	`CampaignExperience`	Award cool points

Asset Management

Method	Returns	Description
`get_assets_page(user_id, limit=10, offset=0)`	`PaginatedResponse[Asset]`	Get a page of assets
`list_all_assets(user_id)`	`list[Asset]`	Get all assets
`iter_all_assets(user_id, limit=100)`	`AsyncIterator[Asset]`	Iterate through assets
`get_asset(user_id, asset_id)`	`Asset`	Retrieve an asset by ID
`upload_asset(user_id, filename, content)`	`Asset`	Upload a new file
`delete_asset(user_id, asset_id)`	`None`	Delete an asset

Notes Management

Method	Returns	Description
`get_notes_page(user_id, limit=10, offset=0)`	`PaginatedResponse[Note]`	Retrieve a paginated page
`list_all_notes(user_id)`	`list[Note]`	Retrieve all notes
`iter_all_notes(user_id, limit=100)`	`AsyncIterator[Note]`	Iterate through all notes
`get_note(user_id, note_id)`	`Note`	Retrieve a note by ID
`create_note(user_id, request=None, **kwargs)`	`Note`	Create a new note
`update_note(user_id, note_id, request=None, **kwargs)`	`Note`	Update note content
`delete_note(user_id, note_id)`	`None`	Delete a note

Quickrolls Management

Method	Returns	Description
`get_quickrolls_page(user_id, limit=10, offset=0)`	`PaginatedResponse[Quickroll]`	Retrieve a paginated page
`list_all_quickrolls(user_id)`	`list[Quickroll]`	Retrieve all quickrolls
`iter_all_quickrolls(user_id, limit=100)`	`AsyncIterator[Quickroll]`	Iterate through all quickrolls
`get_quickroll(user_id, quickroll_id)`	`Quickroll`	Retrieve a quickroll by ID
`create_quickroll(user_id, request=None, **kwargs)`	`Quickroll`	Create a new quickroll
`update_quickroll(user_id, quickroll_id, request=None, **kwargs)`	`Quickroll`	Update quickroll configuration
`delete_quickroll(user_id, quickroll_id)`	`None`	Delete a quickroll

User Roles

Role	Description
`ADMIN`	Full administrative access to company
`STORYTELLER`	Game master role with elevated access
`PLAYER`	Standard player with limited access
`UNAPPROVED`	Registered but not yet approved

Examples

Create a User

Add a new user to the company.

from vclient.models import UserCreate

# Option 1: Use a model object (preferred)
request = UserCreate(
    name_first="John",
    name_last="Doe",
    username="john_doe",
    email="john@example.com",
    role="PLAYER",
    requesting_user_id="admin_user_id"
)
user = await users.create(request=request)

# Option 2: Pass fields as keyword arguments
user = await users.create(
    name_first="John",
    name_last="Doe",
    username="john_doe",
    email="john@example.com",
    role="PLAYER",
    requesting_user_id="admin_user_id"
)

Manage Experience Points

Award or deduct experience points for character progression.

# Get current experience
experience = await users.get_experience(user.id, campaign_id)
print(f"Current XP: {experience.xp_current}")
print(f"Total earned: {experience.xp_total}")

# Award XP (requesting_user_id for permission checking)
updated = await users.add_xp(
    user.id, campaign_id, amount=50, requesting_user_id=admin.id
)
print(f"New XP: {updated.xp_current}")

# Award cool points (converted to XP automatically)
updated = await users.add_cool_points(
    user.id, campaign_id, amount=3, requesting_user_id=admin.id
)

# Deduct XP for character upgrades
updated = await users.remove_xp(
    user.id, campaign_id, amount=20, requesting_user_id=admin.id
)

Create and Manage Notes

Store session notes and character information.

from vclient.models import NoteCreate, NoteUpdate

# Create a note with markdown content
note_request = NoteCreate(
    title="Session 12 Notes",
    content="## Key Events\n\n- Met the Prince\n- Discovered betrayal"
)
note = await users.create_note(user.id, note_request)

# Update note content
update = NoteUpdate(content="Updated content here...")
updated = await users.update_note(user.id, note.id, update)

# List all notes
notes = await users.list_all_notes(user.id)
for note in notes:
    print(f"{note.title}: {len(note.content)} characters")

Create Quickrolls

Set up pre-configured dice pools for common actions.

from vclient.models import QuickrollCreate

# Create a quickroll for a common dice pool
quickroll_request = QuickrollCreate(
    name="Strength + Brawl",
    description="Melee combat attack",
    trait_ids=["trait_strength_id", "trait_brawl_id"]
)
quickroll = await users.create_quickroll(user.id, quickroll_request)

# List all quickrolls
quickrolls = await users.list_all_quickrolls(user.id)
for qr in quickrolls:
    print(f"{qr.name}: {len(qr.trait_ids)} traits")

Upload and Manage Assets

Store character portraits, handouts, and other files.

# Upload a character portrait
with open("portrait.jpg", "rb") as f:
    content = f.read()

asset = await users.upload_asset(
    user.id,
    filename="john_doe_portrait.jpg",
    content=content,
)
print(f"Asset URL: {asset.public_url}")

# List all assets
all_assets = await users.list_all_assets(user.id)
for asset in all_assets:
    print(f"{asset.original_filename}: {asset.asset_type}")

# Delete an asset
await users.delete_asset(user.id, asset.id)

Get Roll Statistics

View aggregated dice roll statistics for a user.

stats = await users.get_statistics(user.id, num_top_traits=10)

print(f"Total rolls: {stats.total_rolls}")
print(f"Success rate: {stats.success_percentage:.1f}%")
print(f"Critical rate: {stats.criticals_percentage:.1f}%")
print(f"Botch rate: {stats.botch_percentage:.1f}%")

Filter Users by Role

Retrieve users filtered by their role in the company.

from vclient.constants import UserRole

# Get all storytellers
storytellers = await users.list_all(user_role=UserRole.STORYTELLER)

# Get paginated list of players
players_page = await users.get_page(user_role=UserRole.PLAYER, limit=25)
print(f"Total players: {players_page.total}")

Approve or Deny Users

Manage the user approval workflow.

from vclient.models import UserApproveDTO

# List all pending users
unapproved = await users.list_all_unapproved()
for user in unapproved:
    print(f"Pending: {user.name_first} {user.name_last} ({user.email})")

# Approve a user as a player
approved = await users.approve_user(
    user_id=user.id,
    role="PLAYER",
    requesting_user_id=admin_user_id,
)
print(f"Approved {approved.name_first} as {approved.role}")

# Deny a user
await users.deny_user(
    user_id=user.id,
    requesting_user_id=admin_user_id,
)

Register a User via SSO

Register a new user through an external auth provider flow (no requesting_user_id needed).

from vclient.models import UserRegisterDTO

# Option 1: Use a model object
request = UserRegisterDTO(
    username="jane_doe",
    email="jane@example.com",
    name_first="Jane",
    name_last="Doe",
)
user = await users.register(request=request)

# Option 2: Pass fields as keyword arguments
user = await users.register(
    username="jane_doe",
    email="jane@example.com",
    name_first="Jane",
    name_last="Doe",
)

Merge Users

Merge an unapproved user's data into an existing primary user.

# Merge secondary user into primary user
merged_user = await users.merge(
    primary_user_id="primary_user_id",
    secondary_user_id="unapproved_user_id",
    requesting_user_id=admin_user_id,
)
print(f"Merged into: {merged_user.username}")

Response Models - View User, UserRegisterDTO, UserMergeDTO, UserApproveDTO, UserDenyDTO, CampaignExperience, Asset, Note, and Quickroll model schemas