@codingfactory/socialkit-vue 0.2.0 → 0.3.0

package/src/services/circles.ts

@@ -0,0 +1,2767 @@
+/**
+ * Configurable circles service for SocialKit-powered frontends.
+ */
+
+import type { AxiosInstance } from 'axios'
+
+export const CIRCLE_MANAGEMENT_SECTIONS = [
+  'overview',
+  'members',
+  'requests',
+  'content',
+  'discussions',
+  'events',
+  'roles',
+  'reports',
+  'bans',
+  'mutes',
+  'audit',
+  'automod',
+  'settings',
+] as const
+
+export type CircleManagementSection = typeof CIRCLE_MANAGEMENT_SECTIONS[number]
+export type CircleVisibility = 'public' | 'closed' | 'secret'
+export type CircleRole = 'owner' | 'admin' | 'moderator' | 'member'
+export type CircleActorRole = CircleRole | null
+export type CircleMembershipRole = 'owner' | 'member'
+export type CircleJoinRequestStatus = 'pending' | 'approved' | 'rejected'
+export type CircleReportStatus = 'pending' | 'actioned' | 'dismissed'
+export type CircleReportDecision = 'action' | 'dismiss'
+export type CircleModerationReportSource = 'member' | 'automod' | (string & {})
+export type CircleModerationReportSubjectType = 'user' | CircleModerationSubjectType | (string & {})
+export type CircleModerationSubjectType = 'post' | 'comment' | 'thread' | 'reply' | 'event'
+export type CircleModerationSubjectState = 'active' | 'removed' | 'locked'
+export type CircleModerationSubjectAction = 'remove' | 'restore' | 'lock' | 'unlock'
+export type CirclePermissionKey =
+  | 'group.details.edit'
+  | 'group.settings.manage'
+  | 'group.visibility.manage'
+  | 'group.rules.manage'
+  | 'group.roles.manage'
+  | 'group.roles.assign'
+  | 'group.members.invite'
+  | 'group.members.remove'
+  | 'group.members.mute'
+  | 'group.members.unmute'
+  | 'group.members.ban'
+  | 'group.members.unban'
+  | 'group.requests.review'
+  | 'group.posts.review'
+  | 'group.posts.remove'
+  | 'group.posts.restore'
+  | 'group.comments.review'
+  | 'group.comments.remove'
+  | 'group.comments.restore'
+  | 'group.discussions.review'
+  | 'group.discussions.lock'
+  | 'group.discussions.unlock'
+  | 'group.discussions.remove'
+  | 'group.discussions.restore'
+  | 'group.events.manage'
+  | 'group.events.remove'
+  | 'group.events.restore'
+  | 'group.reports.review'
+  | 'group.audit.view'
+  | 'group.automod.manage'
+  | 'group.owner.transfer'
+  | (string & {})
+export type CircleAutomodConditionType =
+  | 'keyword_match'
+  | 'regex'
+  | 'account_age'
+  | 'community_karma'
+  | 'link_domains'
+  | string
+export type CircleAutomodActionType = 'remove' | 'flag' | 'approve' | 'add_flair' | string
+
+type UnknownRecord = Record<string, unknown>
+
+export interface CircleUserSummary {
+  id: string
+  name: string
+  handle: string
+  avatar: string | null
+  avatar_url: string | null
+  bio?: string | null
+  is_following?: boolean
+  is_followed_by?: boolean
+}
+
+export interface CircleActorCapabilities {
+  is_owner: boolean
+  is_moderator: boolean
+  moderation_level: CircleRole
+  permissions: CirclePermissionKey[]
+  can: Record<string, boolean>
+  canJoin: boolean
+  canLeave: boolean
+  canRequestToJoin: boolean
+  canInvite: boolean
+  canManage: boolean
+  canManageMembers: boolean
+  canManageRoles: boolean
+  canReviewRequests: boolean
+  canManageReports: boolean
+  canManageBans: boolean
+  canManageMutes: boolean
+  canViewAuditLog: boolean
+  canManageAutomod: boolean
+  canManageSettings: boolean
+  canTransferOwnership: boolean
+  canViewManagement: boolean
+}
+
+export interface CircleActorContext {
+  isMember: boolean
+  role: CircleActorRole
+  hasPendingRequest: boolean
+  capabilities: CircleActorCapabilities
+  managementSections: CircleManagementSection[]
+}
+
+export interface Circle {
+  id: string
+  name: string
+  slug: string
+  description?: string | null
+  visibility: CircleVisibility
+  is_hidden: boolean
+  owner_id?: string | null
+  meta: Record<string, unknown>
+  cover_photo_url?: string | null
+  cover_photo_media_id?: string | null
+  created_at: string
+  updated_at: string
+  is_member?: boolean
+  user_role?: CircleActorRole
+  member_count?: number
+  can_join?: boolean
+  can_manage?: boolean
+  can_manage_members?: boolean
+  can_invite?: boolean
+  can_leave?: boolean
+  can_request_to_join?: boolean
+  has_pending_request?: boolean
+  actor_capabilities?: Partial<CircleActorCapabilities>
+  management_sections?: CircleManagementSection[]
+  group_rules_summary?: string | null
+  welcome_message?: string | null
+  canonical_path?: string | null
+  actor?: CircleActorContext
+  creator?: CircleUserSummary
+}
+
+export interface CircleProfileOverrides {
+  name?: string
+  bio?: string
+  avatar_url?: string
+}
+
+export interface CircleMember {
+  id: string
+  user_id: string
+  circle_id: string
+  role: CircleRole
+  joined_at: string
+  membership_role?: CircleMembershipRole
+  display_role?: CircleRole
+  assigned_roles?: CircleRoleDefinition[]
+  effective_permissions?: CirclePermissionKey[]
+  is_muted?: boolean
+  muted_until?: string | null
+  is_banned?: boolean
+  can_remove?: boolean
+  can_change_role?: boolean
+  can_assign_roles?: boolean
+  can_mute?: boolean
+  can_unmute?: boolean
+  can_ban?: boolean
+  can_unban?: boolean
+  can_view_audit?: boolean
+  profile_overrides?: CircleProfileOverrides
+  user?: CircleUserSummary
+}
+
+export interface JoinRequest {
+  id: string
+  user_id: string
+  circle_id: string
+  status: CircleJoinRequestStatus
+  source: 'direct' | 'invite'
+  message?: string | null
+  reviewed_by_id?: string | null
+  reviewed_at?: string | null
+  created_at: string
+  updated_at: string
+  user?: CircleUserSummary
+}
+
+export interface InviteLink {
+  id: string
+  token: string
+  circle_id: string
+  target_user_id: string | null
+  max_uses: number | null
+  uses_count: number
+  expires_at: string | null
+  invite_url: string
+  qr_svg: string
+}
+
+export interface CircleInviteSearchUser {
+  id: string
+  name: string
+  handle: string
+  avatar_url: string | null
+}
+
+export interface CircleRoleDefinition {
+  id: string
+  slug: string
+  name: string
+  description: string | null
+  color: string | null
+  is_system: boolean
+  is_assignable: boolean
+  member_count: number
+  permissions: CirclePermissionKey[]
+}
+
+/**
+ * @deprecated Use CircleRoleDefinition. Kept only as a temporary compatibility export.
+ */
+export interface CircleRoleAssignment extends CircleRoleDefinition {
+  id: string
+  user_id?: string
+  role?: CircleRole
+  assigned_at?: string | null
+  user?: CircleUserSummary
+}
+
+export interface CirclePermissionCatalogEntry {
+  key: CirclePermissionKey
+  label: string
+  description: string
+  module: string
+  owner_only: boolean
+  surfaced: boolean
+  section: CircleManagementSection
+}
+
+export interface CircleManagementCounts {
+  members: number
+  requests_pending: number
+  reports_pending: number
+  roles: number
+  bans_active: number
+  mutes_active: number
+}
+
+export interface CircleMemberRoleAssignmentResult {
+  assigned_roles: CircleRoleDefinition[]
+  effective_permissions: CirclePermissionKey[]
+}
+
+export interface CircleOwnershipTransferResult {
+  circle_id: string
+  previous_owner_id: string
+  new_owner_id: string
+}
+
+export interface CircleModerationReport {
+  id: string
+  reporter_id: string | null
+  source: CircleModerationReportSource
+  subject_user_id: string | null
+  subject_type: CircleModerationReportSubjectType | null
+  subject_id: string | null
+  subject_author_id: string | null
+  category: string
+  notes?: string | null
+  status: CircleReportStatus
+  priority: string
+  resolution_action?: string | null
+  created_at: string
+  reviewed_at?: string | null
+  resolution_notes?: string | null
+}
+
+export interface CircleBanRecord {
+  id: string
+  user_id: string
+  reason?: string | null
+  created_at: string
+  updated_at?: string | null
+  created_by_id?: string | null
+  user?: CircleUserSummary
+}
+
+export interface CircleMuteRecord {
+  id: string
+  user_id: string
+  reason?: string | null
+  muted_until?: string | null
+  created_at: string
+  updated_at?: string | null
+  created_by_id?: string | null
+  user?: CircleUserSummary
+}
+
+export interface CircleModerationAuditLogEntry {
+  id: string
+  action: string
+  actor_id: string
+  target_user_id: string | null
+  report_id: string | null
+  meta: Record<string, unknown>
+  created_at: string
+}
+
+export interface CircleModerationSubject {
+  subject_type: CircleModerationSubjectType
+  subject_id: string
+  circle_id: string
+  author_id: string | null
+  report_count: number
+  latest_report_status: CircleReportStatus | null
+  moderation_state: CircleModerationSubjectState
+  created_at: string
+  updated_at: string
+  preview: Record<string, unknown>
+  available_actions: CircleModerationSubjectAction[]
+}
+
+export interface CircleAutomodCondition {
+  type: CircleAutomodConditionType
+  config: Record<string, unknown>
+}
+
+export interface CircleAutomodAction {
+  type: CircleAutomodActionType
+  config: Record<string, unknown>
+}
+
+export interface CircleAutomodRule {
+  id: string
+  name: string
+  description?: string | null
+  is_enabled: boolean
+  conditions: CircleAutomodCondition[]
+  actions: CircleAutomodAction[]
+  priority: number
+  created_at: string
+}
+
+export interface CircleManagementBootstrap {
+  circle: Circle
+  actor: CircleActorContext
+  management_sections: CircleManagementSection[]
+  members: PaginationResponse<CircleMember>
+  requests: PaginationResponse<JoinRequest>
+  roles: PaginationResponse<CircleRoleDefinition>
+  counts: CircleManagementCounts
+  permission_catalog: CirclePermissionCatalogEntry[]
+  reports: PaginationResponse<CircleModerationReport>
+  bans: PaginationResponse<CircleBanRecord>
+  mutes: PaginationResponse<CircleMuteRecord>
+  audit: PaginationResponse<CircleModerationAuditLogEntry>
+  automod: PaginationResponse<CircleAutomodRule>
+}
+
+export interface CircleFilters {
+  visibility?: CircleVisibility
+  membership?: 'joined' | 'managed' | 'available'
+  search?: string
+}
+
+export interface PaginationResponse<T> {
+  data: T[]
+  meta: {
+    pagination: {
+      next_cursor: string | null
+      has_more: boolean
+    }
+  }
+}
+
+export interface CircleAutomodRuleInput {
+  name: string
+  description?: string | null
+  is_enabled?: boolean
+  conditions: CircleAutomodCondition[]
+  actions: CircleAutomodAction[]
+  priority?: number
+}
+
+export interface CircleCreateInput {
+  name: string
+  slug?: string
+  description?: string
+  visibility: CircleVisibility
+  is_hidden?: boolean
+  meta?: Record<string, unknown>
+}
+
+export interface CircleUpdateInput {
+  name?: string
+  slug?: string
+  description?: string | null
+  visibility?: CircleVisibility
+  is_hidden?: boolean
+  meta?: Record<string, unknown>
+}
+
+export interface CircleRoleDefinitionInput {
+  name: string
+  description?: string | null
+  color?: string | null
+  clone_from_role_id?: string | null
+  permissions?: CirclePermissionKey[]
+}
+
+export interface CircleRoleDefinitionUpdateInput {
+  name?: string
+  description?: string | null
+  color?: string | null
+}
+
+export interface CircleOwnershipTransferOptions {
+  note?: string | null
+  assign_previous_owner_admin?: boolean
+}
+
+export interface CircleBanMemberOptions {
+  reason?: string
+}
+
+export interface CircleMuteMemberOptions {
+  reason?: string
+  muted_until?: string
+}
+
+export interface CircleInviteLinkOptions {
+  max_uses?: number
+  expires_in_minutes?: number
+  target_user_id?: string
+}
+
+export interface CircleInviteLinkRequestOptions {
+  showSuccessToast?: boolean
+}
+
+export interface CirclesNotification {
+  description: string
+  color: 'success' | 'error' | 'warning'
+  duration?: number
+}
+
+export interface CircleTermOptions {
+  case?: 'title'
+}
+
+export interface CirclesServiceErrorContext {
+  error: unknown
+  url?: string
+  status?: number
+  timestamp: string
+  logLevel: 'warn' | 'error'
+}
+
+export interface CirclesServiceConfig {
+  client: AxiosInstance
+  sanitizeString?: (value: string) => string
+  onNotify?: (notification: CirclesNotification) => void
+  onUnauthorized?: () => void
+  getCircleTerm?: (options?: CircleTermOptions) => string
+  onError?: (context: CirclesServiceErrorContext) => void
+}
+
+type SanitizedInput<T> = T extends string
+  ? string
+  : T extends Array<infer U>
+    ? SanitizedInput<U>[]
+    : T extends Record<string, unknown>
+      ? { [K in keyof T]: SanitizedInput<T[K]> }
+      : T
+
+interface ApiError {
+  config?: { url?: string }
+  response?: { status?: number; data?: { message?: string } }
+}
+
+const DEFAULT_LIST_LIMIT = '10'
+
+function isApiError(value: unknown): value is ApiError {
+  return typeof value === 'object' && value !== null
+}
+
+function isRecord(value: unknown): value is UnknownRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function readRecord(value: unknown, key: string): UnknownRecord | null {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const entry = value[key]
+  return isRecord(entry) ? entry : null
+}
+
+function readArray(value: unknown, key: string): unknown[] | null {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const entry = value[key]
+  return Array.isArray(entry) ? entry : null
+}
+
+function readString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null
+}
+
+function readNullableString(value: unknown): string | null {
+  if (value === null || value === undefined) {
+    return null
+  }
+
+  return readString(value)
+}
+
+function readBoolean(value: unknown): boolean | null {
+  return typeof value === 'boolean' ? value : null
+}
+
+function readNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null
+}
+
+function isCircleVisibility(value: unknown): value is CircleVisibility {
+  return value === 'public' || value === 'closed' || value === 'secret'
+}
+
+function isCircleRole(value: unknown): value is CircleRole {
+  return value === 'owner' || value === 'admin' || value === 'moderator' || value === 'member'
+}
+
+function isCircleMembershipRole(value: unknown): value is CircleMembershipRole {
+  return value === 'owner' || value === 'member'
+}
+
+function isCircleModerationReportSource(value: unknown): value is CircleModerationReportSource {
+  return value === 'member' || value === 'automod' || typeof value === 'string'
+}
+
+function isCircleModerationReportSubjectType(value: unknown): value is CircleModerationReportSubjectType {
+  return value === 'user' || value === 'post' || value === 'comment' || value === 'thread' || value === 'reply' || value === 'event' || typeof value === 'string'
+}
+
+function isManagementSection(value: unknown): value is CircleManagementSection {
+  return typeof value === 'string' && CIRCLE_MANAGEMENT_SECTIONS.includes(value as CircleManagementSection)
+}
+
+function createEmptyPagination<T>(): PaginationResponse<T> {
+  return {
+    data: [],
+    meta: {
+      pagination: {
+        next_cursor: null,
+        has_more: false,
+      },
+    },
+  }
+}
+
+function createEmptyManagementCounts(): CircleManagementCounts {
+  return {
+    members: 0,
+    requests_pending: 0,
+    reports_pending: 0,
+    roles: 0,
+    bans_active: 0,
+    mutes_active: 0,
+  }
+}
+
+function normalizeManagementSections(value: unknown): CircleManagementSection[] {
+  if (!Array.isArray(value)) {
+    return []
+  }
+
+  return value.filter((section): section is CircleManagementSection => isManagementSection(section))
+}
+
+function normalizePermissionKeys(value: unknown): CirclePermissionKey[] {
+  if (!Array.isArray(value)) {
+    return []
+  }
+
+  return value
+    .map((entry) => readString(entry))
+    .filter((entry): entry is CirclePermissionKey => entry !== null)
+}
+
+function normalizePermissionMap(value: unknown): Record<string, boolean> {
+  if (!isRecord(value)) {
+    return {}
+  }
+
+  const normalized: Record<string, boolean> = {}
+
+  for (const [key, entry] of Object.entries(value)) {
+    const flag = readBoolean(entry)
+    if (flag !== null) {
+      normalized[key] = flag
+    }
+  }
+
+  return normalized
+}
+
+function normalizeManagementCounts(value: unknown): CircleManagementCounts {
+  if (!isRecord(value)) {
+    return createEmptyManagementCounts()
+  }
+
+  return {
+    members: readNumber(value.members) ?? 0,
+    requests_pending: readNumber(value.requests_pending) ?? 0,
+    reports_pending: readNumber(value.reports_pending) ?? 0,
+    roles: readNumber(value.roles) ?? 0,
+    bans_active: readNumber(value.bans_active) ?? 0,
+    mutes_active: readNumber(value.mutes_active) ?? 0,
+  }
+}
+
+function normalizeUserSummary(value: unknown): CircleUserSummary | undefined {
+  if (!isRecord(value)) {
+    return undefined
+  }
+
+  const id = readString(value.id)
+  const name = readString(value.name)
+  const handle = readString(value.handle)
+
+  if (id === null || name === null || handle === null) {
+    return undefined
+  }
+
+  const avatar = readNullableString(value.avatar_url) ?? readNullableString(value.avatar)
+  const userSummary: CircleUserSummary = {
+    id,
+    name,
+    handle,
+    avatar,
+    avatar_url: avatar,
+    bio: readNullableString(value.bio),
+  }
+
+  const isFollowing = readBoolean(value.is_following)
+  if (isFollowing !== null) {
+    userSummary.is_following = isFollowing
+  }
+
+  const isFollowedBy = readBoolean(value.is_followed_by)
+  if (isFollowedBy !== null) {
+    userSummary.is_followed_by = isFollowedBy
+  }
+
+  return userSummary
+}
+
+function buildDefaultActorCapabilities(
+  role: CircleActorRole,
+  visibility: CircleVisibility,
+  isMember: boolean,
+): CircleActorCapabilities {
+  const canManage = role === 'owner' || role === 'admin'
+  const canManageRoles = role === 'owner'
+  const canReviewRequests = canManage && visibility !== 'public'
+
+  return {
+    is_owner: role === 'owner',
+    is_moderator: role === 'owner' || role === 'admin' || role === 'moderator',
+    moderation_level: role ?? 'member',
+    permissions: [],
+    can: {},
+    canJoin: !isMember && visibility === 'public',
+    canLeave: isMember && role !== 'owner',
+    canRequestToJoin: !isMember && visibility !== 'public',
+    canInvite: isMember,
+    canManage,
+    canManageMembers: canManage,
+    canManageRoles,
+    canReviewRequests,
+    canManageReports: canManage,
+    canManageBans: canManage,
+    canManageMutes: canManage,
+    canViewAuditLog: canManage,
+    canManageAutomod: canManage,
+    canManageSettings: canManage,
+    canTransferOwnership: role === 'owner',
+    canViewManagement: canManage,
+  }
+}
+
+function normalizeActorCapabilities(
+  value: unknown,
+  fallback: CircleActorCapabilities,
+): CircleActorCapabilities {
+  if (!isRecord(value)) {
+    return fallback
+  }
+
+  const permissionMap = normalizePermissionMap(value.can)
+  const permissions = normalizePermissionKeys(value.permissions)
+
+  const hasPermission = (permissionKey: string): boolean => {
+    if (typeof permissionMap[permissionKey] === 'boolean') {
+      return permissionMap[permissionKey]
+    }
+
+    return permissions.includes(permissionKey)
+  }
+
+  const hasAnyPermission = (permissionKeys: readonly string[]): boolean => {
+    return permissionKeys.some((permissionKey) => hasPermission(permissionKey))
+  }
+
+  const getFlag = (keys: readonly string[], defaultValue: boolean): boolean => {
+    for (const key of keys) {
+      const flag = readBoolean(value[key])
+      if (flag !== null) {
+        return flag
+      }
+    }
+
+    return defaultValue
+  }
+
+  const isOwner = getFlag(['isOwner', 'is_owner'], false)
+  const isModerator = getFlag(['isModerator', 'is_moderator'], false)
+  const moderationLevel = isCircleRole(value.moderation_level)
+    ? value.moderation_level
+    : isOwner
+      ? 'owner'
+      : isModerator
+        ? fallback.moderation_level === 'admin'
+          ? 'admin'
+          : 'moderator'
+        : fallback.moderation_level
+  const canManageDerived = isOwner || isModerator || hasAnyPermission([
+    'group.details.edit',
+    'group.settings.manage',
+    'group.visibility.manage',
+    'group.rules.manage',
+    'group.roles.manage',
+    'group.roles.assign',
+    'group.members.invite',
+    'group.members.remove',
+    'group.members.mute',
+    'group.members.unmute',
+    'group.members.ban',
+    'group.members.unban',
+    'group.requests.review',
+    'group.reports.review',
+    'group.audit.view',
+    'group.automod.manage',
+    'group.owner.transfer',
+  ])
+  const canManageMembersDerived = hasAnyPermission([
+    'group.members.invite',
+    'group.members.remove',
+    'group.members.mute',
+    'group.members.unmute',
+    'group.members.ban',
+    'group.members.unban',
+    'group.roles.assign',
+  ])
+  const canManageRolesDerived = hasAnyPermission([
+    'group.roles.manage',
+    'group.roles.assign',
+  ])
+  const canReviewRequestsDerived = hasPermission('group.requests.review')
+  const canManageReportsDerived = hasPermission('group.reports.review')
+  const canManageBansDerived = hasAnyPermission(['group.members.ban', 'group.members.unban'])
+  const canManageMutesDerived = hasAnyPermission(['group.members.mute', 'group.members.unmute'])
+  const canViewAuditLogDerived = hasPermission('group.audit.view')
+  const canManageAutomodDerived = hasPermission('group.automod.manage')
+  const canManageSettingsDerived = hasAnyPermission([
+    'group.details.edit',
+    'group.settings.manage',
+    'group.visibility.manage',
+    'group.rules.manage',
+  ])
+  const canTransferOwnershipDerived = hasPermission('group.owner.transfer')
+
+  return {
+    is_owner: isOwner || fallback.is_owner,
+    is_moderator: isModerator || fallback.is_moderator,
+    moderation_level: moderationLevel,
+    permissions: permissions.length > 0 ? permissions : fallback.permissions,
+    can: Object.keys(permissionMap).length > 0 ? permissionMap : fallback.can,
+    canJoin: getFlag(['canJoin', 'can_join'], fallback.canJoin),
+    canLeave: getFlag(['canLeave', 'can_leave'], fallback.canLeave),
+    canRequestToJoin: getFlag(['canRequestToJoin', 'can_request_to_join'], fallback.canRequestToJoin),
+    canInvite: getFlag(['canInvite', 'can_invite'], hasPermission('group.members.invite') || fallback.canInvite),
+    canManage: getFlag(['canManage', 'can_manage'], canManageDerived || fallback.canManage),
+    canManageMembers: getFlag(['canManageMembers', 'can_manage_members'], canManageMembersDerived || fallback.canManageMembers),
+    canManageRoles: getFlag(['canManageRoles', 'can_manage_roles'], canManageRolesDerived || fallback.canManageRoles),
+    canReviewRequests: getFlag(['canReviewRequests', 'can_review_requests'], canReviewRequestsDerived || fallback.canReviewRequests),
+    canManageReports: getFlag(['canManageReports', 'can_manage_reports'], canManageReportsDerived || fallback.canManageReports),
+    canManageBans: getFlag(['canManageBans', 'can_manage_bans'], canManageBansDerived || fallback.canManageBans),
+    canManageMutes: getFlag(['canManageMutes', 'can_manage_mutes'], canManageMutesDerived || fallback.canManageMutes),
+    canViewAuditLog: getFlag(['canViewAuditLog', 'can_view_audit_log'], canViewAuditLogDerived || fallback.canViewAuditLog),
+    canManageAutomod: getFlag(['canManageAutomod', 'can_manage_automod'], canManageAutomodDerived || fallback.canManageAutomod),
+    canManageSettings: getFlag(['canManageSettings', 'can_manage_settings'], canManageSettingsDerived || fallback.canManageSettings),
+    canTransferOwnership: getFlag(['canTransferOwnership', 'can_transfer_ownership'], canTransferOwnershipDerived || fallback.canTransferOwnership),
+    canViewManagement: getFlag(['canViewManagement', 'can_view_management'], canManageDerived || fallback.canViewManagement),
+  }
+}
+
+function buildActorContext(circle: Circle): CircleActorContext {
+  const role = isCircleRole(circle.user_role) ? circle.user_role : null
+  const isMember = circle.is_member === true || role !== null
+  const defaultCapabilities = buildDefaultActorCapabilities(role, circle.visibility, isMember)
+  const capabilities = normalizeActorCapabilities(circle.actor_capabilities ?? null, {
+    ...defaultCapabilities,
+    canJoin: circle.can_join ?? defaultCapabilities.canJoin,
+    canLeave: circle.can_leave ?? defaultCapabilities.canLeave,
+    canRequestToJoin: circle.can_request_to_join ?? defaultCapabilities.canRequestToJoin,
+    canInvite: circle.can_invite ?? defaultCapabilities.canInvite,
+    canManage: circle.can_manage ?? defaultCapabilities.canManage,
+    canManageMembers: circle.can_manage_members ?? defaultCapabilities.canManageMembers,
+  })
+
+  const defaultSections = capabilities.canViewManagement
+    ? [...CIRCLE_MANAGEMENT_SECTIONS]
+    : []
+  const managementSections = circle.management_sections && circle.management_sections.length > 0
+    ? [...circle.management_sections]
+    : defaultSections
+
+  return {
+    isMember,
+    role,
+    hasPendingRequest: circle.has_pending_request === true,
+    capabilities,
+    managementSections,
+  }
+}
+
+function normalizeCollectionResponse<T>(
+  payload: unknown,
+  normalizeItem: (value: unknown) => T | null,
+): PaginationResponse<T> {
+  const data = readRecord(payload, 'data') ?? (isRecord(payload) ? payload : null)
+  const dataItems = readArray(payload, 'data')
+  const meta = readRecord(payload, 'meta')
+  const dataMeta = readRecord(data, 'meta')
+  const pagination = readRecord(meta, 'pagination') ?? readRecord(dataMeta, 'pagination')
+  const itemsValue = Array.isArray(data?.items)
+    ? data.items
+    : dataItems ?? (Array.isArray(payload) ? payload : null)
+  const items = Array.isArray(itemsValue)
+    ? itemsValue.map((item) => normalizeItem(item)).filter((item): item is T => item !== null)
+    : []
+
+  const nextCursor = readNullableString(pagination?.next_cursor)
+    ?? readNullableString(data?.next)
+  const hasMore = readBoolean(pagination?.has_more) ?? (nextCursor !== null)
+
+  return {
+    data: items,
+    meta: {
+      pagination: {
+        next_cursor: nextCursor,
+        has_more: hasMore,
+      },
+    },
+  }
+}
+
+function normalizeInlineCollection<T>(
+  items: unknown,
+  normalizeItem: (value: unknown) => T | null,
+): PaginationResponse<T> {
+  if (!Array.isArray(items)) {
+    return createEmptyPagination<T>()
+  }
+
+  return {
+    data: items.map((item) => normalizeItem(item)).filter((item): item is T => item !== null),
+    meta: createEmptyPagination<T>().meta,
+  }
+}
+
+function normalizeCircle(value: unknown): Circle | null {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const id = readString(value.id)
+  const name = readString(value.name)
+  const slug = readString(value.slug)
+  const visibility = value.visibility
+
+  if (id === null || name === null || slug === null || !isCircleVisibility(visibility)) {
+    return null
+  }
+
+  const managementSections = normalizeManagementSections(value.management_sections)
+  const circle: Circle = {
+    id,
+    name,
+    slug,
+    description: readNullableString(value.description),
+    visibility,
+    is_hidden: readBoolean(value.is_hidden) ?? false,
+    owner_id: readNullableString(value.owner_id),
+    meta: isRecord(value.meta) ? value.meta : {},
+    cover_photo_url: readNullableString(value.cover_photo_url),
+    cover_photo_media_id: readNullableString(value.cover_photo_media_id),
+    created_at: readString(value.created_at) ?? new Date(0).toISOString(),
+    updated_at: readString(value.updated_at) ?? new Date(0).toISOString(),
+    user_role: isCircleRole(value.user_role) ? value.user_role : null,
+    group_rules_summary: readNullableString(value.group_rules_summary),
+    welcome_message: readNullableString(value.welcome_message),
+    canonical_path: readNullableString(value.canonical_path),
+  }
+
+  const isMember = readBoolean(value.is_member)
+  if (isMember !== null) {
+    circle.is_member = isMember
+  }
+
+  const memberCount = readNumber(value.member_count)
+  if (memberCount !== null) {
+    circle.member_count = memberCount
+  }
+
+  const canJoin = readBoolean(value.can_join)
+  if (canJoin !== null) {
+    circle.can_join = canJoin
+  }
+
+  const canManage = readBoolean(value.can_manage)
+  if (canManage !== null) {
+    circle.can_manage = canManage
+  }
+
+  const canManageMembers = readBoolean(value.can_manage_members)
+  if (canManageMembers !== null) {
+    circle.can_manage_members = canManageMembers
+  }
+
+  const canInvite = readBoolean(value.can_invite)
+  if (canInvite !== null) {
+    circle.can_invite = canInvite
+  }
+
+  const canLeave = readBoolean(value.can_leave)
+  if (canLeave !== null) {
+    circle.can_leave = canLeave
+  }
+
+  const canRequestToJoin = readBoolean(value.can_request_to_join)
+  if (canRequestToJoin !== null) {
+    circle.can_request_to_join = canRequestToJoin
+  }
+
+  const hasPendingRequest = readBoolean(value.has_pending_request)
+  if (hasPendingRequest !== null) {
+    circle.has_pending_request = hasPendingRequest
+  }
+
+  if (isRecord(value.actor_capabilities)) {
+    circle.actor_capabilities = normalizeActorCapabilities(
+      value.actor_capabilities,
+      buildDefaultActorCapabilities(null, visibility, false),
+    )
+  }
+
+  if (managementSections.length > 0) {
+    circle.management_sections = managementSections
+  }
+
+  const creator = normalizeUserSummary(value.creator)
+  if (creator) {
+    circle.creator = creator
+  }
+
+  circle.actor = buildActorContext(circle)
+  circle.actor_capabilities = circle.actor.capabilities
+  circle.management_sections = circle.actor.managementSections
+  circle.can_join = circle.actor.capabilities.canJoin
+  circle.can_leave = circle.actor.capabilities.canLeave
+  circle.can_request_to_join = circle.actor.capabilities.canRequestToJoin
+  circle.can_invite = circle.actor.capabilities.canInvite
+  circle.can_manage = circle.actor.capabilities.canManage
+  circle.can_manage_members = circle.actor.capabilities.canManageMembers
+  circle.has_pending_request = circle.actor.hasPendingRequest
+  circle.is_member = circle.actor.isMember
+  circle.user_role = circle.actor.role
+
+  return circle
+}
+
+function normalizeCircleMember(value: unknown): CircleMember | null {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const id = readString(value.id)
+  const userId = readString(value.user_id) ?? id
+  const circleId = readString(value.circle_id) ?? ''
+  const joinedAt = readString(value.joined_at)
+  const role = value.role
+
+  if (id === null || userId === null || joinedAt === null || !isCircleRole(role)) {
+    return null
+  }
+
+  const user = normalizeUserSummary(value.user)
+  const profileOverridesValue = isRecord(value.profile_overrides) ? value.profile_overrides : null
+  let profileOverrides: CircleProfileOverrides | undefined
+  if (profileOverridesValue !== null) {
+    const nextProfileOverrides: CircleProfileOverrides = {}
+    const overrideName = readString(profileOverridesValue.name)
+    if (overrideName !== null) {
+      nextProfileOverrides.name = overrideName
+    }
+
+    const overrideBio = readString(profileOverridesValue.bio)
+    if (overrideBio !== null) {
+      nextProfileOverrides.bio = overrideBio
+    }
+
+    const overrideAvatarUrl = readString(profileOverridesValue.avatar_url)
+    if (overrideAvatarUrl !== null) {
+      nextProfileOverrides.avatar_url = overrideAvatarUrl
+    }
+
+    if (Object.keys(nextProfileOverrides).length > 0) {
+      profileOverrides = nextProfileOverrides
+    }
+  }
+
+  const member: CircleMember = {
+    id,
+    user_id: userId,
+    circle_id: circleId,
+    role,
+    joined_at: joinedAt,
+  }
+
+  if (isCircleMembershipRole(value.membership_role)) {
+    member.membership_role = value.membership_role
+  }
+
+  if (isCircleRole(value.display_role)) {
+    member.display_role = value.display_role
+  }
+
+  const assignedRoles = Array.isArray(value.assigned_roles)
+    ? value.assigned_roles
+      .map((roleDefinition) => normalizeRoleDefinition(roleDefinition))
+      .filter((roleDefinition): roleDefinition is CircleRoleDefinition => roleDefinition !== null)
+    : []
+  if (assignedRoles.length > 0) {
+    member.assigned_roles = assignedRoles
+  }
+
+  const effectivePermissions = normalizePermissionKeys(value.effective_permissions)
+  if (effectivePermissions.length > 0) {
+    member.effective_permissions = effectivePermissions
+  }
+
+  const isMuted = readBoolean(value.is_muted)
+  if (isMuted !== null) {
+    member.is_muted = isMuted
+  }
+
+  const mutedUntil = readNullableString(value.muted_until)
+  if (mutedUntil !== null || value.muted_until === null) {
+    member.muted_until = mutedUntil
+  }
+
+  const isBanned = readBoolean(value.is_banned)
+  if (isBanned !== null) {
+    member.is_banned = isBanned
+  }
+
+  const canRemove = readBoolean(value.can_remove)
+  if (canRemove !== null) {
+    member.can_remove = canRemove
+  }
+
+  const canChangeRole = readBoolean(value.can_change_role)
+  if (canChangeRole !== null) {
+    member.can_change_role = canChangeRole
+  }
+
+  const canAssignRoles = readBoolean(value.can_assign_roles)
+  if (canAssignRoles !== null) {
+    member.can_assign_roles = canAssignRoles
+  }
+
+  const canMute = readBoolean(value.can_mute)
+  if (canMute !== null) {
+    member.can_mute = canMute
+  }
+
+  const canUnmute = readBoolean(value.can_unmute)
+  if (canUnmute !== null) {
+    member.can_unmute = canUnmute
+  }
+
+  const canBan = readBoolean(value.can_ban)
+  if (canBan !== null) {
+    member.can_ban = canBan
+  }
+
+  const canUnban = readBoolean(value.can_unban)
+  if (canUnban !== null) {
+    member.can_unban = canUnban
+  }
+
+  const canViewAudit = readBoolean(value.can_view_audit)
+  if (canViewAudit !== null) {
+    member.can_view_audit = canViewAudit
+  }
+
+  if (profileOverrides) {
+    member.profile_overrides = profileOverrides
+  }
+
+  if (user) {
+    member.user = user
+  }
+
+  return member
+}
+
+function normalizeJoinRequest(value: unknown): JoinRequest | null {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const id = readString(value.id)
+  const userId = readString(value.user_id)
+  const circleId = readString(value.circle_id)
+  const status = value.status
+  const source = value.source
+  const createdAt = readString(value.created_at)
+  const updatedAt = readString(value.updated_at)
+
+  if (
+    id === null
+    || userId === null
+    || circleId === null
+    || createdAt === null
+    || updatedAt === null
+    || (status !== 'pending' && status !== 'approved' && status !== 'rejected')
+    || (source !== 'direct' && source !== 'invite')
+  ) {
+    return null
+  }
+
+  const joinRequest: JoinRequest = {
+    id,
+    user_id: userId,
+    circle_id: circleId,
+    status,
+    source,
+    message: readNullableString(value.message),
+    reviewed_by_id: readNullableString(value.reviewed_by_id),
+    reviewed_at: readNullableString(value.reviewed_at),
+    created_at: createdAt,
+    updated_at: updatedAt,
+  }
+
+  const user = normalizeUserSummary(value.user)
+  if (user) {
+    joinRequest.user = user
+  }
+
+  return joinRequest
+}
+
+function normalizeInviteLink(value: unknown): InviteLink | null {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const id = readString(value.id)
+  const token = readString(value.token)
+  const circleId = readString(value.circle_id)
+  const inviteUrl = readString(value.invite_url)
+  const qrSvg = readString(value.qr_svg)
+  const usesCount = readNumber(value.uses_count)
+
+  if (id === null || token === null || circleId === null || inviteUrl === null || qrSvg === null || usesCount === null) {
+    return null
+  }
+
+  return {
+    id,
+    token,
+    circle_id: circleId,
+    target_user_id: readNullableString(value.target_user_id),
+    max_uses: readNumber(value.max_uses),
+    uses_count: usesCount,
+    expires_at: readNullableString(value.expires_at),
+    invite_url: inviteUrl,
+    qr_svg: qrSvg,
+  }
+}
+
+function normalizeRoleDefinition(value: unknown): CircleRoleDefinition | null {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const id = readString(value.id)
+  const slug = readString(value.slug)
+  const name = readString(value.name)
+
+  if (id === null || slug === null || name === null) {
+    return null
+  }
+
+  return {
+    id,
+    slug,
+    name,
+    description: readNullableString(value.description),
+    color: readNullableString(value.color),
+    is_system: readBoolean(value.is_system) ?? false,
+    is_assignable: readBoolean(value.is_assignable) ?? true,
+    member_count: readNumber(value.member_count) ?? 0,
+    permissions: normalizePermissionKeys(value.permissions),
+  }
+}
+
+function normalizePermissionCatalogEntry(value: unknown): CirclePermissionCatalogEntry | null {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const key = readString(value.key)
+  const label = readString(value.label)
+  const description = readString(value.description)
+  const moduleName = readString(value.module)
+  const section = value.section
+
+  if (key === null || label === null || description === null || moduleName === null || !isManagementSection(section)) {
+    return null
+  }
+
+  return {
+    key,
+    label,
+    description,
+    module: moduleName,
+    owner_only: readBoolean(value.owner_only) ?? false,
+    surfaced: readBoolean(value.surfaced) ?? false,
+    section,
+  }
+}
+
+function normalizeModerationReport(value: unknown): CircleModerationReport | null {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const id = readString(value.id) ?? readString(value.report_id)
+  const reporterId = readNullableString(value.reporter_id)
+  const source = isCircleModerationReportSource(value.source)
+    ? value.source
+    : 'member'
+  const subjectUserId = readNullableString(value.subject_user_id)
+  const subjectType = isCircleModerationReportSubjectType(value.subject_type)
+    ? value.subject_type
+    : subjectUserId !== null
+      ? 'user'
+      : null
+  const subjectId = readNullableString(value.subject_id) ?? subjectUserId
+  const subjectAuthorId = readNullableString(value.subject_author_id)
+    ?? (subjectType === 'user' ? subjectUserId : null)
+  const category = readString(value.category) ?? 'general'
+  const status = value.status
+  const priority = readString(value.priority) ?? 'normal'
+  const createdAt = readString(value.created_at) ?? new Date(0).toISOString()
+
+  if (
+    id === null
+    || (status !== 'pending' && status !== 'actioned' && status !== 'dismissed')
+  ) {
+    return null
+  }
+
+  return {
+    id,
+    reporter_id: reporterId,
+    source,
+    subject_user_id: subjectUserId,
+    subject_type: subjectType,
+    subject_id: subjectId,
+    subject_author_id: subjectAuthorId,
+    category,
+    notes: readNullableString(value.notes),
+    status,
+    priority,
+    resolution_action: readNullableString(value.resolution_action),
+    created_at: createdAt,
+    reviewed_at: readNullableString(value.reviewed_at),
+    resolution_notes: readNullableString(value.resolution_notes),
+  }
+}
+
+function normalizeBanRecord(value: unknown): CircleBanRecord | null {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const id = readString(value.id) ?? readString(value.user_id)
+  const userId = readString(value.user_id)
+  const createdAt = readString(value.created_at) ?? new Date(0).toISOString()
+
+  if (id === null || userId === null) {
+    return null
+  }
+
+  const banRecord: CircleBanRecord = {
+    id,
+    user_id: userId,
+    reason: readNullableString(value.reason),
+    created_at: createdAt,
+    updated_at: readNullableString(value.updated_at),
+    created_by_id: readNullableString(value.created_by_id),
+  }
+
+  const user = normalizeUserSummary(value.user)
+  if (user) {
+    banRecord.user = user
+  }
+
+  return banRecord
+}
+
+function normalizeMuteRecord(value: unknown): CircleMuteRecord | null {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const id = readString(value.id) ?? readString(value.user_id)
+  const userId = readString(value.user_id)
+  const createdAt = readString(value.created_at) ?? new Date(0).toISOString()
+
+  if (id === null || userId === null) {
+    return null
+  }
+
+  const muteRecord: CircleMuteRecord = {
+    id,
+    user_id: userId,
+    reason: readNullableString(value.reason),
+    muted_until: readNullableString(value.muted_until),
+    created_at: createdAt,
+    updated_at: readNullableString(value.updated_at),
+    created_by_id: readNullableString(value.created_by_id),
+  }
+
+  const user = normalizeUserSummary(value.user)
+  if (user) {
+    muteRecord.user = user
+  }
+
+  return muteRecord
+}
+
+function normalizeAuditLogEntry(value: unknown): CircleModerationAuditLogEntry | null {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const id = readString(value.id)
+  const action = readString(value.action)
+  const actorId = readString(value.actor_id)
+  const createdAt = readString(value.created_at) ?? new Date(0).toISOString()
+
+  if (id === null || action === null || actorId === null) {
+    return null
+  }
+
+  return {
+    id,
+    action,
+    actor_id: actorId,
+    target_user_id: readNullableString(value.target_user_id),
+    report_id: readNullableString(value.report_id),
+    meta: isRecord(value.meta) ? value.meta : {},
+    created_at: createdAt,
+  }
+}
+
+function isCircleModerationSubjectType(value: unknown): value is CircleModerationSubjectType {
+  return value === 'post' || value === 'comment' || value === 'thread' || value === 'reply' || value === 'event'
+}
+
+function isCircleModerationSubjectState(value: unknown): value is CircleModerationSubjectState {
+  return value === 'active' || value === 'removed' || value === 'locked'
+}
+
+function isCircleModerationSubjectAction(value: unknown): value is CircleModerationSubjectAction {
+  return value === 'remove' || value === 'restore' || value === 'lock' || value === 'unlock'
+}
+
+function normalizeModerationSubject(value: unknown): CircleModerationSubject | null {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const subjectType = value.subject_type
+  const subjectId = readString(value.subject_id)
+  const circleId = readString(value.circle_id)
+  const moderationState = value.moderation_state
+  const createdAt = readString(value.created_at)
+  const updatedAt = readString(value.updated_at)
+
+  if (
+    subjectId === null
+    || circleId === null
+    || createdAt === null
+    || updatedAt === null
+    || !isCircleModerationSubjectType(subjectType)
+    || !isCircleModerationSubjectState(moderationState)
+  ) {
+    return null
+  }
+
+  const actions = Array.isArray(value.available_actions)
+    ? value.available_actions
+      .filter((entry): entry is CircleModerationSubjectAction => isCircleModerationSubjectAction(entry))
+    : []
+
+  const latestReportStatusValue = value.latest_report_status
+  const latestReportStatus: CircleReportStatus | null = latestReportStatusValue === 'pending'
+    || latestReportStatusValue === 'actioned'
+    || latestReportStatusValue === 'dismissed'
+    ? latestReportStatusValue
+    : null
+
+  return {
+    subject_type: subjectType,
+    subject_id: subjectId,
+    circle_id: circleId,
+    author_id: readNullableString(value.author_id),
+    report_count: readNumber(value.report_count) ?? 0,
+    latest_report_status: latestReportStatus,
+    moderation_state: moderationState,
+    created_at: createdAt,
+    updated_at: updatedAt,
+    preview: isRecord(value.preview) ? value.preview : {},
+    available_actions: actions,
+  }
+}
+
+function normalizeAutomodCondition(value: unknown): CircleAutomodCondition | null {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const type = readString(value.type)
+  if (type === null) {
+    return null
+  }
+
+  return {
+    type,
+    config: isRecord(value.config) ? value.config : {},
+  }
+}
+
+function normalizeAutomodAction(value: unknown): CircleAutomodAction | null {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const type = readString(value.type)
+  if (type === null) {
+    return null
+  }
+
+  return {
+    type,
+    config: isRecord(value.config) ? value.config : {},
+  }
+}
+
+function normalizeAutomodRule(value: unknown): CircleAutomodRule | null {
+  if (!isRecord(value)) {
+    return null
+  }
+
+  const id = readString(value.id)
+  const name = readString(value.name)
+  const createdAt = readString(value.created_at) ?? new Date(0).toISOString()
+
+  if (id === null || name === null) {
+    return null
+  }
+
+  const conditions = Array.isArray(value.conditions)
+    ? value.conditions.map((condition) => normalizeAutomodCondition(condition)).filter((condition): condition is CircleAutomodCondition => condition !== null)
+    : []
+  const actions = Array.isArray(value.actions)
+    ? value.actions.map((action) => normalizeAutomodAction(action)).filter((action): action is CircleAutomodAction => action !== null)
+    : []
+
+  return {
+    id,
+    name,
+    description: readNullableString(value.description),
+    is_enabled: readBoolean(value.is_enabled) ?? true,
+    conditions,
+    actions,
+    priority: readNumber(value.priority) ?? 0,
+    created_at: createdAt,
+  }
+}
+
+function isCircleWithSlug(value: unknown): value is { id: string; slug: string } {
+  if (!isRecord(value)) {
+    return false
+  }
+
+  return typeof value.id === 'string' && typeof value.slug === 'string'
+}
+
+function defaultSanitizeString(value: string): string {
+  return value.trim()
+}
+
+function defaultGetCircleTerm(options?: CircleTermOptions): string {
+  return options?.case === 'title' ? 'Circle' : 'circle'
+}
+
+class CirclesService {
+  private readonly baseURL = '/v1/circles'
+
+  public constructor(
+    private readonly client: AxiosInstance,
+    private readonly sanitizeString: (value: string) => string,
+    private readonly onNotify?: (notification: CirclesNotification) => void,
+    private readonly onUnauthorized?: () => void,
+    private readonly getCircleTerm: (options?: CircleTermOptions) => string = defaultGetCircleTerm,
+    private readonly onError?: (context: CirclesServiceErrorContext) => void,
+  ) {}
+
+  private isUuid(value: string): boolean {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)
+  }
+
+  private sanitizeInput<T>(data: T): SanitizedInput<T> {
+    if (typeof data === 'string') {
+      return this.sanitizeString(data.trim()) as SanitizedInput<T>
+    }
+
+    if (Array.isArray(data)) {
+      return data.map((item) => this.sanitizeInput(item)) as SanitizedInput<T>
+    }
+
+    if (isRecord(data)) {
+      const sanitized: Record<string, unknown> = {}
+      Object.keys(data).forEach((key) => {
+        sanitized[key] = this.sanitizeInput(data[key])
+      })
+      return sanitized as SanitizedInput<T>
+    }
+
+    return data as SanitizedInput<T>
+  }
+
+  private emitNotification(notification: CirclesNotification): void {
+    this.onNotify?.(notification)
+  }
+
+  private reportError(context: CirclesServiceErrorContext): void {
+    const consoleMethod = context.logLevel === 'warn' ? console.warn : console.error
+    const label = context.logLevel === 'warn' ? 'Circles API Not Found:' : 'Circles API Error:'
+
+    consoleMethod(label, {
+      url: context.url,
+      status: context.status,
+      timestamp: context.timestamp,
+    })
+
+    this.onError?.(context)
+  }
+
+  private async handleError(error: unknown): Promise<never> {
+    const apiError = isApiError(error) ? error : null
+    const status = apiError?.response?.status
+    const context: CirclesServiceErrorContext = {
+      error,
+      url: apiError?.config?.url,
+      status,
+      timestamp: new Date().toISOString(),
+      logLevel: status === 404 ? 'warn' : 'error',
+    }
+
+    this.reportError(context)
+
+    let userMessage = 'Something went wrong. Please try again.'
+
+    switch (status) {
+      case 401:
+        userMessage = 'Please sign in to continue.'
+        this.onUnauthorized?.()
+        break
+      case 403:
+        userMessage = `You do not have permission to access this ${this.getCircleTerm()}.`
+        break
+      case 404:
+        userMessage = `${this.getCircleTerm({ case: 'title' })} not found.`
+        break
+      case 422:
+        userMessage = readString(apiError?.response?.data?.message) ?? 'Please check your input and try again.'
+        break
+      case 429:
+        userMessage = 'Too many requests. Please wait a moment.'
+        break
+    }
+
+    this.emitNotification({
+      description: userMessage,
+      color: 'error',
+      duration: 4000,
+    })
+
+    throw new Error(userMessage)
+  }
+
+  private isHttpStatus(error: unknown, status: number): boolean {
+    return isApiError(error) && error.response?.status === status
+  }
+
+  private async findBySlug(slug: string): Promise<Circle | null> {
+    const response = await this.client.get(this.baseURL, {
+      params: {
+        search: this.sanitizeInput(slug),
+        limit: DEFAULT_LIST_LIMIT,
+      },
+    })
+
+    const items = readRecord(response.data, 'data')?.items
+    if (!Array.isArray(items)) {
+      return null
+    }
+
+    const normalizedSlug = slug.trim().toLowerCase()
+    const matchedCircle = items.find((item: unknown) => isCircleWithSlug(item) && item.slug.toLowerCase() === normalizedSlug)
+
+    return matchedCircle ? normalizeCircle(matchedCircle) : null
+  }
+
+  public async list(cursor?: string | null, filters?: CircleFilters): Promise<PaginationResponse<Circle>> {
+    try {
+      const params: Record<string, string> = {
+        limit: DEFAULT_LIST_LIMIT,
+      }
+
+      if (cursor) {
+        params.cursor = cursor
+      }
+
+      if (filters?.visibility) {
+        params.visibility = filters.visibility
+      }
+
+      if (filters?.membership) {
+        params.membership = filters.membership
+      }
+
+      if (filters?.search) {
+        params.search = this.sanitizeInput(filters.search)
+      }
+
+      const response = await this.client.get(this.baseURL, { params })
+      return normalizeCollectionResponse(response.data, normalizeCircle)
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async get(id: string): Promise<Circle> {
+    const identifier = this.sanitizeInput(id)
+
+    try {
+      const response = await this.client.get(`${this.baseURL}/${identifier}`)
+      const data = readRecord(response.data, 'data') ?? (isRecord(response.data) ? response.data : null)
+      const normalized = normalizeCircle(data?.circle ?? data)
+
+      if (normalized !== null) {
+        return normalized
+      }
+
+      throw new Error('Invalid circle payload')
+    } catch (error: unknown) {
+      if (this.isHttpStatus(error, 404) && !this.isUuid(identifier)) {
+        try {
+          const matchedCircle = await this.findBySlug(identifier)
+          if (matchedCircle !== null) {
+            return matchedCircle
+          }
+        } catch {
+          // Fall through to canonical error handling.
+        }
+      }
+
+      return await this.handleError(error)
+    }
+  }
+
+  public async create(data: CircleCreateInput): Promise<{ id: string }> {
+    try {
+      const response = await this.client.post(this.baseURL, this.sanitizeInput(data))
+      const payload = readRecord(response.data, 'data') ?? {}
+      const id = readString(payload.id)
+
+      if (id === null) {
+        throw new Error('Invalid circle creation payload')
+      }
+
+      return { id }
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async update(id: string, data: CircleUpdateInput): Promise<Circle> {
+    try {
+      await this.client.patch(`${this.baseURL}/${id}`, this.sanitizeInput(data))
+      return await this.get(id)
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async delete(id: string): Promise<void> {
+    try {
+      await this.client.delete(`${this.baseURL}/${id}`)
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async join(id: string): Promise<void> {
+    try {
+      await this.client.post(`${this.baseURL}/${id}/join`)
+      this.emitNotification({
+        description: `Successfully joined ${this.getCircleTerm()}!`,
+        color: 'success',
+      })
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async leave(id: string): Promise<void> {
+    try {
+      await this.client.post(`${this.baseURL}/${id}/leave`)
+      this.emitNotification({
+        description: `Left ${this.getCircleTerm()} successfully`,
+        color: 'success',
+      })
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async getMembers(id: string, cursor?: string | null): Promise<PaginationResponse<CircleMember>> {
+    try {
+      const params: Record<string, string> = {}
+      if (cursor) {
+        params.cursor = cursor
+      }
+
+      const response = await this.client.get(`${this.baseURL}/${id}/members`, { params })
+      return normalizeCollectionResponse(response.data, normalizeCircleMember)
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async requestToJoin(id: string, message?: string): Promise<{ request_id: string; status: string }> {
+    try {
+      const body: Record<string, string> = {}
+      if (message) {
+        body.message = this.sanitizeInput(message)
+      }
+
+      const response = await this.client.post(`${this.baseURL}/${id}/join-requests`, body)
+      const payload = readRecord(response.data, 'data') ?? {}
+      const requestId = readString(payload.request_id)
+      const status = readString(payload.status)
+
+      if (requestId === null || status === null) {
+        throw new Error('Invalid join request payload')
+      }
+
+      this.emitNotification({
+        description: `Join request sent! The ${this.getCircleTerm()} admins will review it.`,
+        color: 'success',
+        duration: 4000,
+      })
+
+      return {
+        request_id: requestId,
+        status,
+      }
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async listJoinRequests(circleId: string, cursor?: string | null, status?: string): Promise<PaginationResponse<JoinRequest>> {
+    try {
+      const params: Record<string, string> = {}
+      if (cursor) {
+        params.cursor = cursor
+      }
+      if (status) {
+        params.status = status
+      }
+
+      const response = await this.client.get(`${this.baseURL}/${circleId}/join-requests`, { params })
+      return normalizeCollectionResponse(response.data, normalizeJoinRequest)
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async moderateJoinRequest(circleId: string, requestId: string, decision: 'approve' | 'reject'): Promise<{ request_id: string; status: string }> {
+    try {
+      const response = await this.client.patch(`${this.baseURL}/${circleId}/join-requests/${requestId}`, { decision })
+      const payload = readRecord(response.data, 'data') ?? {}
+      const status = readString(payload.status)
+      const resolvedRequestId = readString(payload.request_id) ?? requestId
+
+      if (status === null) {
+        throw new Error('Invalid join request moderation payload')
+      }
+
+      this.emitNotification({
+        description: `Join request ${decision === 'approve' ? 'approved' : 'rejected'}.`,
+        color: decision === 'approve' ? 'success' : 'warning',
+      })
+
+      return {
+        request_id: resolvedRequestId,
+        status,
+      }
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async fetchRoleDefinitions(circleId: string, cursor?: string | null): Promise<PaginationResponse<CircleRoleDefinition>> {
+    return await this.listRoleDefinitions(circleId, cursor)
+  }
+
+  public async listRoleDefinitions(circleId: string, cursor?: string | null): Promise<PaginationResponse<CircleRoleDefinition>> {
+    try {
+      const params: Record<string, string> = {}
+      if (cursor) {
+        params.cursor = cursor
+      }
+
+      const response = await this.client.get(`${this.baseURL}/${circleId}/roles`, { params })
+      const directCollection = normalizeCollectionResponse(response.data, normalizeRoleDefinition)
+      if (directCollection.data.length > 0 || directCollection.meta.pagination.has_more) {
+        return directCollection
+      }
+
+      const data = readRecord(response.data, 'data')
+      const roles = readArray(response.data, 'data') ?? data?.roles ?? data?.items
+      if (Array.isArray(roles)) {
+        return normalizeInlineCollection(roles, normalizeRoleDefinition)
+      }
+
+      return createEmptyPagination<CircleRoleDefinition>()
+    } catch (error: unknown) {
+      if (this.isHttpStatus(error, 404)) {
+        return createEmptyPagination<CircleRoleDefinition>()
+      }
+
+      return await this.handleError(error)
+    }
+  }
+
+  public async listRoles(circleId: string, cursor?: string | null): Promise<PaginationResponse<CircleRoleDefinition>> {
+    return await this.listRoleDefinitions(circleId, cursor)
+  }
+
+  public async createRoleDefinition(circleId: string, input: CircleRoleDefinitionInput): Promise<CircleRoleDefinition> {
+    try {
+      const response = await this.client.post(`${this.baseURL}/${circleId}/roles`, this.sanitizeInput(input))
+      const data = readRecord(response.data, 'data') ?? (isRecord(response.data) ? response.data : null)
+      const normalized = normalizeRoleDefinition(data)
+
+      if (normalized !== null) {
+        this.emitNotification({
+          description: 'Group role created.',
+          color: 'success',
+        })
+        return normalized
+      }
+
+      throw new Error('Invalid group role payload')
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async createRole(circleId: string, input: CircleRoleDefinitionInput): Promise<CircleRoleDefinition> {
+    return await this.createRoleDefinition(circleId, input)
+  }
+
+  public async updateRoleDefinition(circleId: string, roleId: string, input: CircleRoleDefinitionUpdateInput): Promise<CircleRoleDefinition> {
+    try {
+      const response = await this.client.patch(`${this.baseURL}/${circleId}/roles/${roleId}`, this.sanitizeInput(input))
+      const data = readRecord(response.data, 'data') ?? (isRecord(response.data) ? response.data : null)
+      const normalized = normalizeRoleDefinition(data)
+
+      if (normalized !== null) {
+        this.emitNotification({
+          description: 'Group role updated.',
+          color: 'success',
+        })
+        return normalized
+      }
+
+      throw new Error('Invalid group role payload')
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async updateRole(circleId: string, roleId: string, input: CircleRoleDefinitionUpdateInput): Promise<CircleRoleDefinition> {
+    return await this.updateRoleDefinition(circleId, roleId, input)
+  }
+
+  public async replaceRoleDefinitionPermissions(
+    circleId: string,
+    roleId: string,
+    permissions: CirclePermissionKey[],
+  ): Promise<CircleRoleDefinition> {
+    try {
+      const response = await this.client.put(`${this.baseURL}/${circleId}/roles/${roleId}/permissions`, {
+        permissions: this.sanitizeInput(permissions),
+      })
+      const data = readRecord(response.data, 'data') ?? (isRecord(response.data) ? response.data : null)
+      const normalized = normalizeRoleDefinition(data)
+
+      if (normalized !== null) {
+        this.emitNotification({
+          description: 'Group role permissions updated.',
+          color: 'success',
+        })
+        return normalized
+      }
+
+      throw new Error('Invalid group role payload')
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async replaceRolePermissions(
+    circleId: string,
+    roleId: string,
+    permissions: CirclePermissionKey[],
+  ): Promise<CircleRoleDefinition> {
+    return await this.replaceRoleDefinitionPermissions(circleId, roleId, permissions)
+  }
+
+  public async archiveRoleDefinition(circleId: string, roleId: string): Promise<void> {
+    try {
+      await this.client.delete(`${this.baseURL}/${circleId}/roles/${roleId}`)
+      this.emitNotification({
+        description: 'Group role archived.',
+        color: 'success',
+      })
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async archiveRole(circleId: string, roleId: string): Promise<void> {
+    return await this.archiveRoleDefinition(circleId, roleId)
+  }
+
+  public async assignMemberRoles(
+    circleId: string,
+    userId: string,
+    roleIds: string[],
+  ): Promise<CircleMemberRoleAssignmentResult> {
+    try {
+      const response = await this.client.post(`${this.baseURL}/${circleId}/members/${userId}/roles`, {
+        role_ids: this.sanitizeInput(roleIds),
+      })
+      const data = readRecord(response.data, 'data')
+
+      return {
+        assigned_roles: Array.isArray(data?.assigned_roles)
+          ? data.assigned_roles
+            .map((roleDefinition) => normalizeRoleDefinition(roleDefinition))
+            .filter((roleDefinition): roleDefinition is CircleRoleDefinition => roleDefinition !== null)
+          : [],
+        effective_permissions: normalizePermissionKeys(data?.effective_permissions),
+      }
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async removeMemberRole(circleId: string, userId: string, roleId: string): Promise<void> {
+    try {
+      await this.client.delete(`${this.baseURL}/${circleId}/members/${userId}/roles/${roleId}`)
+      this.emitNotification({
+        description: 'Member role removed.',
+        color: 'success',
+      })
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async changeMemberRole(circleId: string, userId: string, role: 'admin' | 'member'): Promise<void> {
+    try {
+      try {
+        await this.client.patch(`${this.baseURL}/${circleId}/roles/${userId}`, { role })
+      } catch (error: unknown) {
+        if (!this.isHttpStatus(error, 404) && !this.isHttpStatus(error, 405)) {
+          throw error
+        }
+
+        await this.client.patch(`${this.baseURL}/${circleId}/members/role`, { user_id: userId, role })
+      }
+
+      const roleLabel = role === 'admin' ? 'an admin' : 'a member'
+      this.emitNotification({
+        description: `Member role changed to ${roleLabel}.`,
+        color: 'success',
+      })
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async transferOwnership(
+    circleId: string,
+    userId: string,
+    options?: CircleOwnershipTransferOptions,
+  ): Promise<CircleOwnershipTransferResult> {
+    try {
+      const payload: Record<string, string | boolean> = {
+        user_id: userId,
+      }
+
+      if (typeof options?.note === 'string' && options.note.trim().length > 0) {
+        payload.note = this.sanitizeInput(options.note)
+      }
+
+      if (typeof options?.assign_previous_owner_admin === 'boolean') {
+        payload.assign_previous_owner_admin = options.assign_previous_owner_admin
+      }
+
+      const response = await this.client.post(`${this.baseURL}/${circleId}/owner/transfer`, payload)
+      const data = readRecord(response.data, 'data') ?? {}
+      const resolvedCircleId = readString(data.circle_id)
+      const previousOwnerId = readString(data.previous_owner_id)
+      const newOwnerId = readString(data.new_owner_id)
+
+      if (resolvedCircleId === null || previousOwnerId === null || newOwnerId === null) {
+        throw new Error('Invalid ownership transfer payload')
+      }
+
+      this.emitNotification({
+        description: `${this.getCircleTerm({ case: 'title' })} ownership transferred.`,
+        color: 'success',
+      })
+
+      return {
+        circle_id: resolvedCircleId,
+        previous_owner_id: previousOwnerId,
+        new_owner_id: newOwnerId,
+      }
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async removeMember(circleId: string, userId: string): Promise<void> {
+    try {
+      await this.client.delete(`${this.baseURL}/${circleId}/members`, { data: { user_id: userId } })
+      this.emitNotification({
+        description: `Member removed from ${this.getCircleTerm()}.`,
+        color: 'success',
+      })
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async banMember(circleId: string, userId: string, options?: CircleBanMemberOptions): Promise<void> {
+    try {
+      const payload: Record<string, string> = { user_id: userId }
+      if (typeof options?.reason === 'string' && options.reason.trim().length > 0) {
+        payload.reason = this.sanitizeInput(options.reason)
+      }
+
+      await this.client.post(`${this.baseURL}/${circleId}/moderation/bans`, payload)
+      this.emitNotification({
+        description: `Member banned from ${this.getCircleTerm()}.`,
+        color: 'success',
+      })
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async listBans(circleId: string, cursor?: string | null): Promise<PaginationResponse<CircleBanRecord>> {
+    try {
+      const params: Record<string, string> = {}
+      if (cursor) {
+        params.cursor = cursor
+      }
+
+      const response = await this.client.get(`${this.baseURL}/${circleId}/moderation/bans`, { params })
+      return normalizeCollectionResponse(response.data, normalizeBanRecord)
+    } catch (error: unknown) {
+      if (this.isHttpStatus(error, 404)) {
+        return createEmptyPagination<CircleBanRecord>()
+      }
+
+      return await this.handleError(error)
+    }
+  }
+
+  public async unbanMember(circleId: string, userId: string): Promise<void> {
+    try {
+      await this.client.delete(`${this.baseURL}/${circleId}/moderation/bans/${userId}`)
+      this.emitNotification({
+        description: `Member unbanned in ${this.getCircleTerm()}.`,
+        color: 'success',
+      })
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async muteMember(
+    circleId: string,
+    userId: string,
+    options?: CircleMuteMemberOptions,
+  ): Promise<void> {
+    try {
+      const payload: Record<string, string> = { user_id: userId }
+      if (typeof options?.reason === 'string' && options.reason.trim().length > 0) {
+        payload.reason = this.sanitizeInput(options.reason)
+      }
+      if (typeof options?.muted_until === 'string' && options.muted_until.trim().length > 0) {
+        payload.muted_until = options.muted_until.trim()
+      }
+
+      await this.client.post(`${this.baseURL}/${circleId}/moderation/mutes`, payload)
+      this.emitNotification({
+        description: `Member muted in ${this.getCircleTerm()}.`,
+        color: 'success',
+      })
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async listMutes(circleId: string, cursor?: string | null): Promise<PaginationResponse<CircleMuteRecord>> {
+    try {
+      const params: Record<string, string> = {}
+      if (cursor) {
+        params.cursor = cursor
+      }
+
+      const response = await this.client.get(`${this.baseURL}/${circleId}/moderation/mutes`, { params })
+      return normalizeCollectionResponse(response.data, normalizeMuteRecord)
+    } catch (error: unknown) {
+      if (this.isHttpStatus(error, 404)) {
+        return createEmptyPagination<CircleMuteRecord>()
+      }
+
+      return await this.handleError(error)
+    }
+  }
+
+  public async unmuteMember(circleId: string, userId: string): Promise<void> {
+    try {
+      await this.client.delete(`${this.baseURL}/${circleId}/moderation/mutes/${userId}`)
+      this.emitNotification({
+        description: `Member unmuted in ${this.getCircleTerm()}.`,
+        color: 'success',
+      })
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async reportMember(
+    circleId: string,
+    subjectUserId: string,
+    category: string,
+    notes?: string,
+  ): Promise<{ report_id: string; status: string }> {
+    try {
+      const payload: Record<string, string> = {
+        subject_user_id: subjectUserId,
+        category: this.sanitizeInput(category),
+      }
+      if (typeof notes === 'string' && notes.trim().length > 0) {
+        payload.notes = this.sanitizeInput(notes)
+      }
+
+      const response = await this.client.post(`${this.baseURL}/${circleId}/moderation/reports`, payload)
+      const data = readRecord(response.data, 'data') ?? {}
+      const reportId = readString(data.report_id)
+      const status = readString(data.status)
+
+      if (reportId === null || status === null) {
+        throw new Error('Invalid moderation report payload')
+      }
+
+      this.emitNotification({
+        description: 'Report submitted for review.',
+        color: 'success',
+      })
+
+      return {
+        report_id: reportId,
+        status,
+      }
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async listModerationReports(
+    circleId: string,
+    cursor?: string | null,
+    status?: CircleReportStatus,
+  ): Promise<PaginationResponse<CircleModerationReport>> {
+    try {
+      const params: Record<string, string> = {}
+      if (cursor) {
+        params.cursor = cursor
+      }
+      if (status) {
+        params.status = status
+      }
+
+      const response = await this.client.get(`${this.baseURL}/${circleId}/moderation/reports`, { params })
+      return normalizeCollectionResponse(response.data, normalizeModerationReport)
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async resolveModerationReport(
+    circleId: string,
+    reportId: string,
+    decision: CircleReportDecision,
+    resolutionNotes?: string,
+  ): Promise<{ report_id: string; status: string }> {
+    try {
+      const payload: Record<string, string> = { decision }
+      if (typeof resolutionNotes === 'string' && resolutionNotes.trim().length > 0) {
+        payload.resolution_notes = this.sanitizeInput(resolutionNotes)
+      }
+
+      const response = await this.client.patch(`${this.baseURL}/${circleId}/moderation/reports/${reportId}`, payload)
+      const data = readRecord(response.data, 'data') ?? {}
+      const resolvedReportId = readString(data.report_id) ?? reportId
+      const status = readString(data.status)
+
+      if (status === null) {
+        throw new Error('Invalid moderation resolution payload')
+      }
+
+      this.emitNotification({
+        description: `Report ${decision === 'action' ? 'actioned' : 'dismissed'}.`,
+        color: 'success',
+      })
+
+      return {
+        report_id: resolvedReportId,
+        status,
+      }
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async getModerationAuditLog(circleId: string, cursor?: string | null): Promise<PaginationResponse<CircleModerationAuditLogEntry>> {
+    try {
+      const params: Record<string, string> = {}
+      if (cursor) {
+        params.cursor = cursor
+      }
+
+      const response = await this.client.get(`${this.baseURL}/${circleId}/moderation/audit-log`, { params })
+      return normalizeCollectionResponse(response.data, normalizeAuditLogEntry)
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async listModerationSubjects(
+    circleId: string,
+    subjectType: CircleModerationSubjectType,
+    cursor?: string | null,
+    state?: CircleModerationSubjectState | 'all',
+  ): Promise<PaginationResponse<CircleModerationSubject>> {
+    try {
+      const params: Record<string, string> = {
+        subject_type: subjectType,
+      }
+
+      if (cursor) {
+        params.cursor = cursor
+      }
+
+      if (state) {
+        params.state = state
+      }
+
+      const response = await this.client.get(`${this.baseURL}/${circleId}/moderation/subjects`, { params })
+      return normalizeCollectionResponse(response.data, normalizeModerationSubject)
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async actOnModerationSubject(
+    circleId: string,
+    subjectType: CircleModerationSubjectType,
+    subjectId: string,
+    action: CircleModerationSubjectAction,
+    reason?: string,
+  ): Promise<void> {
+    try {
+      const payload: Record<string, string> = { action }
+      if (typeof reason === 'string' && reason.trim().length > 0) {
+        payload.reason = this.sanitizeInput(reason)
+      }
+
+      await this.client.post(`${this.baseURL}/${circleId}/moderation/subjects/${subjectType}/${subjectId}/actions`, payload)
+
+      this.emitNotification({
+        description: `Moderation action "${action}" applied.`,
+        color: 'success',
+      })
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async listAutomodRules(circleId: string, cursor?: string | null): Promise<PaginationResponse<CircleAutomodRule>> {
+    try {
+      const params: Record<string, string> = {}
+      if (cursor) {
+        params.cursor = cursor
+      }
+
+      const response = await this.client.get(`${this.baseURL}/${circleId}/automod-rules`, { params })
+      return normalizeCollectionResponse(response.data, normalizeAutomodRule)
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async getAutomodRule(circleId: string, ruleId: string): Promise<CircleAutomodRule> {
+    try {
+      const response = await this.client.get(`${this.baseURL}/${circleId}/automod-rules/${ruleId}`)
+      const data = readRecord(response.data, 'data') ?? (isRecord(response.data) ? response.data : null)
+      const normalized = normalizeAutomodRule(data)
+
+      if (normalized !== null) {
+        return normalized
+      }
+
+      throw new Error('Invalid automod rule payload')
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async createAutomodRule(circleId: string, input: CircleAutomodRuleInput): Promise<CircleAutomodRule> {
+    try {
+      const response = await this.client.post(`${this.baseURL}/${circleId}/automod-rules`, this.sanitizeInput(input))
+      const data = readRecord(response.data, 'data') ?? (isRecord(response.data) ? response.data : null)
+      const normalized = normalizeAutomodRule(data)
+
+      if (normalized !== null) {
+        this.emitNotification({
+          description: 'Automoderation rule created.',
+          color: 'success',
+        })
+        return normalized
+      }
+
+      throw new Error('Invalid automod rule payload')
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async updateAutomodRule(circleId: string, ruleId: string, input: Partial<CircleAutomodRuleInput>): Promise<CircleAutomodRule> {
+    try {
+      const response = await this.client.patch(`${this.baseURL}/${circleId}/automod-rules/${ruleId}`, this.sanitizeInput(input))
+      const data = readRecord(response.data, 'data') ?? (isRecord(response.data) ? response.data : null)
+      const normalized = normalizeAutomodRule(data)
+
+      if (normalized !== null) {
+        this.emitNotification({
+          description: 'Automoderation rule updated.',
+          color: 'success',
+        })
+        return normalized
+      }
+
+      throw new Error('Invalid automod rule payload')
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async deleteAutomodRule(circleId: string, ruleId: string): Promise<void> {
+    try {
+      await this.client.delete(`${this.baseURL}/${circleId}/automod-rules/${ruleId}`)
+      this.emitNotification({
+        description: 'Automoderation rule deleted.',
+        color: 'success',
+      })
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async getManagementBootstrap(circleId: string): Promise<CircleManagementBootstrap> {
+    const identifier = this.sanitizeInput(circleId)
+    let resolvedCircle: Circle | null = null
+    const bootstrapIdentifier = this.isUuid(identifier)
+      ? identifier
+      : await (async (): Promise<string> => {
+        resolvedCircle = await this.get(identifier)
+        return resolvedCircle.id
+      })()
+
+    try {
+      const response = await this.client.get(`${this.baseURL}/${bootstrapIdentifier}/management/bootstrap`)
+      const data = readRecord(response.data, 'data')
+      const bootstrapCircle = data?.circle
+      const bootstrapManagementSections = normalizeManagementSections(data?.management_sections)
+      const directCircle = normalizeCircle(bootstrapCircle ?? data)
+      const mergedCircleSource = directCircle === null
+        ? {
+          ...(resolvedCircle ?? await this.get(bootstrapIdentifier)),
+          ...(bootstrapCircle ?? {}),
+          actor_capabilities: data?.actor_capabilities,
+          management_sections: bootstrapManagementSections.length > 0
+            ? bootstrapManagementSections
+            : undefined,
+        }
+        : {
+          ...directCircle,
+          actor_capabilities: data?.actor_capabilities ?? directCircle.actor_capabilities,
+          management_sections: bootstrapManagementSections.length > 0
+            ? bootstrapManagementSections
+            : directCircle.management_sections,
+        }
+      const circle = normalizeCircle(mergedCircleSource)
+
+      if (circle !== null) {
+        const actor = circle.actor ?? buildActorContext(circle)
+        return {
+          circle,
+          actor,
+          management_sections: bootstrapManagementSections.length > 0
+            ? bootstrapManagementSections
+            : actor.managementSections,
+          members: normalizeCollectionResponse(data?.members ?? {}, normalizeCircleMember),
+          requests: normalizeCollectionResponse(data?.requests ?? {}, normalizeJoinRequest),
+          roles: Array.isArray(data?.roles)
+            ? normalizeInlineCollection(data.roles, normalizeRoleDefinition)
+            : normalizeCollectionResponse(data?.roles ?? {}, normalizeRoleDefinition),
+          counts: normalizeManagementCounts(data?.counts),
+          permission_catalog: Array.isArray(data?.permission_catalog)
+            ? data.permission_catalog
+              .map((entry) => normalizePermissionCatalogEntry(entry))
+              .filter((entry): entry is CirclePermissionCatalogEntry => entry !== null)
+            : [],
+          reports: normalizeCollectionResponse(data?.reports ?? {}, normalizeModerationReport),
+          bans: normalizeCollectionResponse(data?.bans ?? {}, normalizeBanRecord),
+          mutes: normalizeCollectionResponse(data?.mutes ?? {}, normalizeMuteRecord),
+          audit: normalizeCollectionResponse(data?.audit ?? {}, normalizeAuditLogEntry),
+          automod: normalizeCollectionResponse(data?.automod ?? {}, normalizeAutomodRule),
+        }
+      }
+    } catch (error: unknown) {
+      if (!this.isHttpStatus(error, 404)) {
+        return await this.handleError(error)
+      }
+    }
+
+    const circle = resolvedCircle ?? await this.get(identifier)
+    const actor = circle.actor ?? buildActorContext(circle)
+
+    if (!actor.capabilities.canViewManagement) {
+      return {
+        circle,
+        actor,
+        management_sections: actor.managementSections,
+        members: createEmptyPagination<CircleMember>(),
+        requests: createEmptyPagination<JoinRequest>(),
+        roles: createEmptyPagination<CircleRoleDefinition>(),
+        counts: createEmptyManagementCounts(),
+        permission_catalog: [],
+        reports: createEmptyPagination<CircleModerationReport>(),
+        bans: createEmptyPagination<CircleBanRecord>(),
+        mutes: createEmptyPagination<CircleMuteRecord>(),
+        audit: createEmptyPagination<CircleModerationAuditLogEntry>(),
+        automod: createEmptyPagination<CircleAutomodRule>(),
+      }
+    }
+
+    const requestsPromise = actor.capabilities.canReviewRequests
+      ? this.listJoinRequests(circle.id, null, 'pending')
+      : Promise.resolve(createEmptyPagination<JoinRequest>())
+
+    const [
+      members,
+      requests,
+      roles,
+      reports,
+      bans,
+      mutes,
+      audit,
+      automod,
+    ] = await Promise.all([
+      this.getMembers(circle.id),
+      requestsPromise,
+      this.listRoles(circle.id),
+      this.listModerationReports(circle.id, null, 'pending'),
+      this.listBans(circle.id),
+      this.listMutes(circle.id),
+      this.getModerationAuditLog(circle.id),
+      this.listAutomodRules(circle.id),
+    ])
+
+    return {
+      circle,
+      actor,
+      management_sections: actor.managementSections,
+      members,
+      requests,
+      roles,
+      counts: {
+        members: circle.member_count ?? members.data.length,
+        requests_pending: requests.data.length,
+        reports_pending: reports.data.length,
+        roles: roles.data.length,
+        bans_active: bans.data.length,
+        mutes_active: mutes.data.length,
+      },
+      permission_catalog: [],
+      reports,
+      bans,
+      mutes,
+      audit,
+      automod,
+    }
+  }
+
+  public async searchInviteCandidates(circleId: string, query: string): Promise<CircleInviteSearchUser[]> {
+    void circleId
+
+    try {
+      const sanitizedQuery = query.trim()
+      if (sanitizedQuery.length < 2) {
+        return []
+      }
+
+      const response = await this.client.get('/v1/search/aggregate', {
+        params: {
+          q: sanitizedQuery,
+          'types[]': 'user',
+          limit: 10,
+        },
+      })
+
+      const data = readRecord(response.data, 'data') ?? (isRecord(response.data) ? response.data : null)
+      const results = readRecord(data, 'results')
+      const byType = readRecord(results, 'by_type')
+      const users = Array.isArray(byType?.user) ? byType.user : []
+
+      return users
+        .map((entry): CircleInviteSearchUser | null => {
+          if (!isRecord(entry)) {
+            return null
+          }
+
+          const id = readString(entry.id)
+          const name = readString(entry.title)
+          const meta = readRecord(entry, 'meta')
+          const handle = readString(meta?.handle)
+
+          if (id === null || name === null || handle === null) {
+            return null
+          }
+
+          return {
+            id,
+            name,
+            handle,
+            avatar_url: readNullableString(meta?.avatar_url),
+          }
+        })
+        .filter((entry): entry is CircleInviteSearchUser => entry !== null)
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async createInviteLink(
+    circleId: string,
+    options?: CircleInviteLinkOptions,
+    requestOptions?: CircleInviteLinkRequestOptions,
+  ): Promise<InviteLink> {
+    try {
+      const body: Record<string, number | string> = {}
+      if (typeof options?.max_uses === 'number') {
+        body.max_uses = options.max_uses
+      }
+      if (typeof options?.expires_in_minutes === 'number') {
+        body.expires_in_minutes = options.expires_in_minutes
+      }
+      if (typeof options?.target_user_id === 'string' && options.target_user_id.trim() !== '') {
+        body.target_user_id = options.target_user_id
+      }
+
+      const response = await this.client.post(`${this.baseURL}/${circleId}/invite-links`, body)
+      const data = readRecord(response.data, 'data') ?? (isRecord(response.data) ? response.data : null)
+      const normalized = normalizeInviteLink(data)
+
+      if (normalized !== null) {
+        if (requestOptions?.showSuccessToast !== false) {
+          this.emitNotification({
+            description: `Invite link created for ${this.getCircleTerm()}!`,
+            color: 'success',
+          })
+        }
+        return normalized
+      }
+
+      throw new Error('Invalid invite link payload')
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async joinViaInvite(token: string): Promise<{ circle_id: string; requested: boolean }> {
+    try {
+      const response = await this.client.post(`/v1/circle-invites/${encodeURIComponent(token)}/join`)
+      const data = readRecord(response.data, 'data') ?? {}
+      const circleId = readString(data.circle_id)
+      const requested = readBoolean(data.requested)
+
+      if (circleId === null || requested === null) {
+        throw new Error('Invalid invite accept payload')
+      }
+
+      return {
+        circle_id: circleId,
+        requested,
+      }
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async declineInvite(token: string): Promise<void> {
+    try {
+      await this.client.post(`/v1/circle-invites/${encodeURIComponent(token)}/decline`)
+    } catch (error: unknown) {
+      return await this.handleError(error)
+    }
+  }
+
+  public async checkSlugAvailability(slug: string): Promise<boolean> {
+    try {
+      const sanitizedSlug = this.sanitizeInput(slug)
+      const response = await this.client.get(`${this.baseURL}/check-slug`, {
+        params: { slug: sanitizedSlug },
+      })
+
+      const data = readRecord(response.data, 'data')
+      const payloadAvailability = readBoolean(data?.available)
+      const rootAvailability = readBoolean(isRecord(response.data) ? response.data.available : undefined)
+
+      return payloadAvailability ?? rootAvailability ?? true
+    } catch (error: unknown) {
+      if (this.isHttpStatus(error, 404)) {
+        return true
+      }
+
+      return await this.handleError(error)
+    }
+  }
+
+  public generateSlug(name: string): string {
+    if (name.trim().length === 0) {
+      return ''
+    }
+
+    return this.sanitizeInput(name)
+      .toLowerCase()
+      .replace(/[^a-z0-9\s-]/g, '')
+      .replace(/\s+/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^-|-$/g, '')
+      .substring(0, 140)
+  }
+}
+
+export function createCirclesService(config: CirclesServiceConfig) {
+  const {
+    client,
+    sanitizeString = defaultSanitizeString,
+    onNotify,
+    onUnauthorized,
+    getCircleTerm = defaultGetCircleTerm,
+    onError,
+  } = config
+
+  return new CirclesService(
+    client,
+    sanitizeString,
+    onNotify,
+    onUnauthorized,
+    getCircleTerm,
+    onError,
+  )
+}
+
+export type CirclesServiceInstance = ReturnType<typeof createCirclesService>