useAccountTier

Location: src/hooks/useAccountTier.js

Overview

Provides account tier information and tier-based restrictions. New accounts have limited capabilities (cannot create circles, limited friend requests) until they become established through time and activity. The hook fetches tier info via the get_account_tier_info RPC and exposes derived permission flags.

Also exports useTierAwareRateLimit for checking rate limits that vary by account tier, and the constants ACCOUNT_TIERS and TIER_RESTRICTIONS.

Exports

ACCOUNT_TIERS

const ACCOUNT_TIERS = {
  NEW: 'new',
  ESTABLISHED: 'established',
  TRUSTED: 'trusted'
}

TIER_RESTRICTIONS

Tier	Can Create Circles	Can Invite	Friend Requests/Day	New Conversations/Hour
new	No	No	5	3
established	Yes	Yes	20	10
trusted	Yes	Yes	100	50

useAccountTier

function useAccountTier(): {
  // Raw data
  tierInfo: object | null,
  loading: boolean,
  error: string | null,
  // Tier info
  tier: 'new' | 'established' | 'trusted',
  restrictions: TierRestrictions,
  isNewAccount: boolean,
  isEstablished: boolean,
  isTrusted: boolean,
  // Permissions
  canCreateCircles: boolean,
  canInviteToCircles: boolean,
  // Progress (for new accounts)
  daysUntilEligible: number,
  accountAgeDays: number,
  postCount: number,
  needsMorePosts: boolean,
  needsMoreTime: boolean,
  // Actions
  refetch: () => Promise<void>
}

useTierAwareRateLimit

function useTierAwareRateLimit(): {
  rateLimitError: string | null,
  checkLimit: (actionType: string, targetId?: string | null) => Promise<{
    allowed: boolean,
    message: string | null,
    tier?: string,
    remaining?: number,
    isNewAccountRestriction?: boolean
  }>,
  clearError: () => void
}

Parameters

Both hooks take no parameters. They determine the current user internally.

Return Value (useAccountTier)

Property	Type	Description
tierInfo	object | null	Raw tier info from the database
loading	boolean	Whether tier info is being fetched
error	string | null	Error message if fetch failed
tier	string	Current tier: 'new', 'established', or 'trusted'
restrictions	object	Tier restriction object with limits and capabilities
isNewAccount	boolean	Whether the account is in the new tier
isEstablished	boolean	Whether the account is established or trusted
isTrusted	boolean	Whether the account is in the trusted tier
canCreateCircles	boolean	Whether the user can create circles
canInviteToCircles	boolean	Whether the user can invite others to circles
daysUntilEligible	number	Days remaining until tier upgrade eligibility
accountAgeDays	number	Account age in days
postCount	number	Number of posts the user has made
needsMorePosts	boolean	Whether the user needs to post more (< 1 post) for tier upgrade
needsMoreTime	boolean	Whether the user needs more time (< 7 days) for tier upgrade
refetch	() => Promise<void>	Re-fetch tier info

Usage

import { useAccountTier } from '../hooks/useAccountTier';

function CircleCreateButton() {
  const { canCreateCircles, isNewAccount, daysUntilEligible } = useAccountTier();

  if (!canCreateCircles) {
    return (
      <div>
        <button disabled>Create Circle</button>
        {isNewAccount && (
          <p>Available in {daysUntilEligible} days</p>
        )}
      </div>
    );
  }

  return <button onClick={handleCreate}>Create Circle</button>;
}

Notes

• Defaults to 'new' tier on error (safe default per Invariant #18).
• isEstablished is true for both established and trusted tiers.
• The useTierAwareRateLimit hook calls the check_rate_limit_with_tier RPC and fails open (allows the action) if the check itself errors.
• Tier upgrades are determined server-side based on account age and activity.

---

Last updated: 2026-02-07