UsersService
@blobs/sdk / services / UsersService
Defined in: services/UsersService.ts:32
Handles user lookup, search, listing, and profile updates. Reads are cached for cacheTTL
across id, email, and username lookup keys; mutating operations invalidate the relevant
cache entries. Admin-only methods (e.g. adminCreate) require elevated server-side privileges.
Example
const sdk = createSDK({ networks: [...] });const res = await sdk.users.getById('user_123');Constructors
Constructor
new UsersService(
context):UsersService
Defined in: services/UsersService.ts:40
Constructs a UsersService bound to the given context.
Parameters
context
Shared BlobsContext providing transport, cache, and event manager.
Returns
UsersService
Methods
getById()
Defined in: services/UsersService.ts:73
Fetches a user record by ID, served from cache when available.
Parameters
id
string
The user identifier.
useCache?
boolean = true
When true (default), returns a cached value if present; pass false to force a network fetch.
options?
Optional network/tenant scoping options.
Returns
A Response containing the User.
Throws
NotFoundError when no user with the given ID exists.
Remarks
Mirrors the Go SDK GetByID method.
getByEmail()
Defined in: services/UsersService.ts:102
Fetches a user by email address, populating both the email-keyed and id-keyed caches.
Parameters
string
The user’s email address.
options?
Optional network/tenant scoping options.
Returns
A Response containing the User.
Throws
NotFoundError when no user with the given email exists.
getByUsername()
Defined in: services/UsersService.ts:135
Fetches a user by username, populating both the username-keyed and id-keyed caches.
Parameters
username
string
The user’s username.
options?
Optional network/tenant scoping options.
Returns
A Response containing the User.
Throws
NotFoundError when no user with the given username exists.
search()
search(
query,params?,options?):Promise<Response<{items:User[];total?:number; }>>
Defined in: services/UsersService.ts:169
Full-text / prefix search for users via the dedicated /users/search endpoint.
Distinct from list, which uses the plain /users listing endpoint with a search filter.
Parameters
query
string
Search query string.
params?
Optional pagination params (limit, offset).
limit?
number
offset?
number
options?
Optional network/tenant scoping options.
Returns
Promise<Response<{ items: User[]; total?: number; }>>
A Response containing { items: User[], total?: number }.
adminCreate()
Defined in: services/UsersService.ts:202
Admin-only: creates a user directly, bypassing the self-registration flow. Requires the caller to have admin privileges on the backend.
Parameters
input
CreateUserRequest payload describing the new user.
username
string
string
Format: email
password
string
display_name?
string
role?
"user" | "moderator" | "admin"
options?
Optional network/tenant scoping options.
Returns
A Response containing the created User record.
Throws
PermissionError when the caller lacks admin privileges.
Throws
ValidationError when input is rejected.
list()
Defined in: services/UsersService.ts:219
Lists users via the /users endpoint, with optional pagination and a basic search filter.
Parameters
params?
Optional limit, offset, and search filter.
limit?
number
offset?
number
search?
string
options?
Optional network/tenant scoping options.
Returns
A Response containing matching User records.
update()
Defined in: services/UsersService.ts:247
Updates a user record and invalidates the user’s id-keyed cache entry.
Parameters
id
string
The user identifier.
input
Partial user fields to update.
options?
Optional network/tenant scoping options.
Returns
A Response containing the updated User.
Throws
PermissionError when the caller lacks write access to the user.
delete()
delete(
id,options?):Promise<Response<void>>
Defined in: services/UsersService.ts:271
Deletes a user and clears the cache entry.
Parameters
id
string
The user identifier.
options?
Optional network/tenant scoping options.
Returns
Promise<Response<void>>
A Response with no payload on success.
Throws
PermissionError when the caller lacks delete privileges.
subscribe()
subscribe(
event,callback,options?): () =>void
Defined in: services/UsersService.ts:296
Subscribes to a real-time user event by name. Delegates to the unified ctx.wireEvents
manager — see WireEventManager for ordering, buffering, and error-routing semantics.
Parameters
event
string
Wire event name (e.g. user.created, user.profile.updated).
callback
(data) => void
Handler invoked with the event payload.
options?
Optional network/tenant scoping options.
Returns
An unsubscribe function that removes this listener.
() => void
onUserCreated()
onUserCreated(
callback,options?): () =>void
Defined in: services/UsersService.ts:311
Subscribes to user.created events.
Parameters
callback
PlatformEventCallback<UserCreatedEvent>
Handler receiving the typed UserCreatedEvent payload.
options?
Optional network/tenant scoping options.
Returns
An unsubscribe function.
() => void
onUserUpdated()
onUserUpdated(
callback,options?): () =>void
Defined in: services/UsersService.ts:322
Subscribes to user.updated events.
Parameters
callback
PlatformEventCallback<UserUpdatedEvent>
Handler receiving the typed UserUpdatedEvent payload.
options?
Optional network/tenant scoping options.
Returns
An unsubscribe function.
() => void
onUserDeleted()
onUserDeleted(
callback,options?): () =>void
Defined in: services/UsersService.ts:333
Subscribes to user.deleted events.
Parameters
callback
PlatformEventCallback<UserDeletedEvent>
Handler receiving the typed UserDeletedEvent payload.
options?
Optional network/tenant scoping options.
Returns
An unsubscribe function.
() => void
onProfileUpdated()
onProfileUpdated(
callback,options?): () =>void
Defined in: services/UsersService.ts:344
Subscribes to user.profile.updated events fired when a user’s profile data changes.
Parameters
callback
PlatformEventCallback<UserProfileUpdatedEvent>
Handler receiving the typed UserProfileUpdatedEvent payload.
options?
Optional network/tenant scoping options.
Returns
An unsubscribe function.
() => void