pb.packs

A pack is a Packbase community. Call pb.packs(id) with a pack UUID to get a lazy PackHandle. The SDK does not send a request until you await the handle or call one of its methods. Use list methods such as pb.packs.list() and .create() directly on pb.packs.

Fetch and list packs

const pack = await pb.packs('00000000-0000-0000-0000-000000000000')
const result = await pb.packs.list()

console.log(pack.about?.bio)
for (const listedPack of result.packs) {
  console.log(listedPack.display_name)
}
console.log(`${result.hidden} packs hidden because you already belong to them`)

Awaiting a handle returns one Pack. list() returns a PackList object rather than a plain array because the response also includes visibility information:

interface PackList {
  packs: Pack[]
  hidden: number
  total_count?: number
}

Pass { search: 'text' } to filter the complete list. This endpoint has no continuation parameter, so the SDK removes the server's unusable has_more field.

Create a pack

const pack = await pb.packs.create({
  display_name: 'My Art Community',
  description: 'A place for digital artists.',
})

The signed-in user becomes the owner. display_name is limited to 128 characters and description to 256 characters.

Members

const members = await pb.packs('pack-id').members()

for (const member of members) {
  console.log(member.username, member.membership_id, member.roles)
}

This returns all members in one PackMember[]; there is no cursor or page number for this endpoint.

Join and leave

const membership = await pb.packs('pack-id').join()
console.log(membership.tenant_id, membership.user_id)

await pb.packs('pack-id').leave()

Both methods require authentication. Pack owners cannot leave through this endpoint. Users also cannot leave if the target is their default pack.

Edit pack details

const updated = await pb.packs('pack-id').update({
  display_name: 'New Name',
  about: { bio: 'Updated description', flair: 'ART' },
  images: { avatar: 'data:image/png;base64,...' },
})

This operation requires the ManagePack permission. The response is a database PackUpdateResult, not a standard Pack object. Fetch the pack again if the user interface requires the formatted current state.

Settings

const settings = await pb.packs('pack-id').settings()

for (const setting of settings) {
  console.log(setting.key, setting.value, setting.definition)
}

settings() sends GET /pack/:id/settings and returns a discriminated PackSetting[]. Definitions contain type, a typed default, user_modifiable, and display metadata. They also contain type-specific fields such as values or range.

This route is read-only. For a definition with user_modifiable: true, update the current user's value through pb.me.settings():

await pb.me.settings({ allow_rehowl: false })

Roles

Role management requires the ManageRoles permission. Permissions are numeric bit flags, and | combines several flags into one value.

const role = await pack.createRole({
  name: 'Moderator',
  permissions: PackPermissionBits.BanMembers | PackPermissionBits.KickMembers,
})

const roles = await pack.roles()
await pack.updateRole(role.id, {...role, name: 'Senior moderator'})
await pack.setMemberRoles('user-id', [role.id])
await pack.deleteRole(role.id)

setMemberRoles() takes the user's UUID, not the numeric membership record ID. The server strips the Owner permission bit from custom roles.

Moderate members

await pack.kick('user-id')
await pack.ban('user-id')

Despite the route calling it memberId, the value passed to kick() and ban() is the user's UUID.

Pinned howls

const { data: pinned } = await pack.pins()
await pack.pinHowl('howl-id', {expiresAt: '2026-12-31T23:59:00.000Z'})
await pack.unpinHowl('howl-id')

Pinning requires PinHowls. A pack may have at most five active pins.

Report a pack

const ticket = await pb.packs('pack-id').report(
  ReportReason.HarassmentOrBullying,
  'Additional context.',
)

report() returns the created moderation ticket's id and status.