Userverse Dart Client

A Dart and Flutter client for Userverse v0.7.0.

Features

• Login, token refresh/revocation, profile management, and password reset
• Company and company-user management
• Global and company role management
• Global and company permission management
• Role-permission and platform-role assignments
• Typed UUID, pagination, and API error responses

Installation

dependencies:
  userverse_dart_client: ^0.7.0

Then run dart pub get or flutter pub get.

Usage

import 'package:userverse_dart_client/userverse_dart_client.dart';

Future<void> main() async {
  final client = UserverseClient(
    baseUrl: 'http://localhost:8500',
  );

  try {
    final tokens = await client.users.login(
      username: 'user@example.com',
      password: 'password',
    );
    client.setAuthToken(tokens.accessToken);

    final user = await client.users.getMe();
    final permissions = await client.users.getPermissions();

    print('${user.email}: ${permissions.map((p) => p.name).join(', ')}');
  } on ApiException catch (error) {
    print('${error.statusCode}: ${error.message}');
  } finally {
    client.close();
  }
}

RBAC

The v0.7.0 RBAC APIs are grouped by scope:

final permission = await client.permissions.createPermission(
  const PermissionCreate(
    name: 'users.read',
    description: 'Read platform users',
  ),
);

final role = await client.roles.createRole(
  RoleCreate(name: 'Support', description: 'Support staff'),
);

await client.permissions.assignPermissionToRole(
  roleId: role.id!,
  permissionId: permission.id,
);

await client.platformRoles.assignRole(
  userId: 'user-uuid',
  roleId: role.id!,
);

Company-scoped permissions use client.companyPermissions; company roles and members continue to use client.companyRoles and client.companyUsers.

Services

• client.users: Authentication, profiles, memberships, and current-user permissions
• client.companies: Company CRUD
• client.companyUsers: Company membership and member-role updates
• client.companyRoles: Company role management and role-catalog assignment
• client.roles: Global role catalog
• client.permissions: Global permission and role-permission management
• client.companyPermissions: Company permission and role-permission management
• client.platformRoles: Direct platform-role assignments for users

Testing

Run formatting, analysis, and the unit suite locally with:

dart format --output=none --set-exit-if-changed lib test example tool
dart analyze --fatal-infos
dart test
dart run coverage:test_with_coverage --fail-under=80

Live integration tests are opt-in and never silently pass as ordinary tests. They require a disposable or explicitly approved Userverse environment:

USERVERSE_RUN_INTEGRATION=true \
USERVERSE_BASE_URL=http://127.0.0.1:8500 \
USERVERSE_TEST_EMAIL=dart-test@example.com \
USERVERSE_TEST_PASSWORD='replace-with-a-test-password' \
dart test test/integration --concurrency=1

The GitHub Actions integration job checks out Userverse v0.7.0, initializes an isolated SQLite database, creates and bootstraps a disposable superuser, runs the user/company/role/permission flows, and cleans up the API resources. No long-lived integration credentials or database are used.

Migrating from 0.0.1

• User, company, role, and permission IDs are UUID String values.
• Paginated responses read the v0.7.0 current_page field.
• Company-user responses expose a typed role; roleName remains available as a compatibility getter.
• Call client.setAuthToken(token) once instead of passing tokens to individual methods.

See the Userverse documentation for API authorization requirements.

For pull request checks, versioning, and pub.dev releases, see the Release and CI/CD Guide.

Running the example

Provide credentials through environment variables; the example never embeds or prints them:

USERVERSE_BASE_URL=http://localhost:8500 \
USERVERSE_USERNAME=user@example.com \
USERVERSE_PASSWORD='your-password' \
USERVERSE_CLEANUP=true \
dart run example/userverse_dart_client_example.dart

Role-management operations require a Userverse superuser. With cleanup enabled, the example company is deleted after the run, while the supplied user is kept.