Companies Service

Manage companies and developer access permissions.

Usage

from vclient import companies_service

companies = companies_service()

Methods

CRUD Operations

Method	Returns	Description
`get(company_id)`	`Company`	Get a company by ID
`create(CompanyCreate, **kwargs)`	`NewCompanyResponse`	Create a new company
`update(company_id, CompanyUpdate, **kwargs)`	`Company`	Update a company
`delete(company_id)`	`None`	Delete a company

Pagination

Method	Returns	Description
`get_page(limit?, offset?)`	`PaginatedResponse[Company]`	Get a page of companies
`list_all()`	`list[Company]`	Get all companies
`iter_all(limit?)`	`AsyncIterator[Company]`	Iterate through all companies

Permissions

Method	Returns	Description
`grant_access(company_id, developer_id, permission)`	`CompanyPermissions`	Grant, modify, or revoke developer access

Statistics

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

Permission Levels

Level	Description
`USER`	View company data
`ADMIN`	Modify company settings and data
`OWNER`	Full control including managing permissions
`REVOKE`	Remove all access

Permission Considerations

Only company owners can grant or revoke permissions. You cannot revoke access from the last remaining owner of a company.

Example

from vclient.models import CompanyCreate, CompanyUpdate

# Create a company (preferred method: use model object)
request = CompanyCreate(
    name="Dark Haven Games",
    email="contact@darkhaven.com"
)
result = await companies.create(request)
company = result.company
admin_user = result.admin_user

# Alternative: pass fields as keyword arguments
result = await companies.create(
    name="Dark Haven Games",
    email="contact@darkhaven.com"
)

# Update company details
update = CompanyUpdate(name="Dark Haven Gaming")
updated = await companies.update(company.id, update)

# Grant admin access to another developer
permissions = await companies.grant_access(
    company_id=company.id,
    developer_id="507f1f77bcf86cd799439012",
    permission="ADMIN"
)
print(f"Granted {permissions.permission} access")

Statistics

View aggregated dice roll statistics for a company.

stats = await companies.get_statistics(company.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}%")

Audit Logs

View audit trail entries for a company. All filter parameters are optional.

# Get a page of audit logs
page = await companies.get_audit_log_page(
    company.id,
    entity_type="CHARACTER",
    operation="UPDATE",
)

for entry in page.items:
    print(f"{entry.date_created}: {entry.description}")

# Get all audit logs
all_logs = await companies.list_all_audit_logs(company.id)

# Iterate through audit logs
async for log in companies.iter_all_audit_logs(company.id, operation="DELETE"):
    print(f"Deleted: {log.target_entity_id}")

# Include request forensic details
page = await companies.get_audit_log_page(
    company.id,
    include=["request_details"],
)
for entry in page.items:
    print(f"{entry.method} {entry.url}")

Audit Log Methods

Method	Returns	Description
`get_audit_log_page(company_id, **filters)`	`PaginatedResponse[AuditLog \\| AuditLogDetail]`	Get a page of audit log entries
`list_all_audit_logs(company_id, **filters)`	`list[AuditLog \\| AuditLogDetail]`	Get all audit log entries
`iter_all_audit_logs(company_id, **filters)`	`AsyncIterator[AuditLog \\| AuditLogDetail]`	Iterate through all audit log entries

Filter Parameters

Parameter	Type	Description
`acting_user_id`	`str \\| None`	Who performed the action
`user_id`	`str \\| None`	User being acted upon
`campaign_id`	`str \\| None`	Campaign context
`book_id`	`str \\| None`	Book context
`chapter_id`	`str \\| None`	Chapter context
`character_id`	`str \\| None`	Character context
`entity_type`	`AuditEntityType`	Filter by entity type
`operation`	`AuditOperation`	CREATE, UPDATE, or DELETE
`date_from`	`datetime \\| None`	Entries on or after this timestamp
`date_to`	`datetime \\| None`	Entries on or before this timestamp
`include`	`list[AuditLogInclude]`	Pass `["request_details"]` for forensics

See Response Models for Company, CompanySettings, CompanySettingsCreate, CompanySettingsUpdate, and related types. See Audit Log Models for AuditLog and AuditLogDetail field details.