@playstack/accounts-react

@playstack/accounts-react exposes account selection state without merging account membership into the authentication client.

Use it for

• Loading the accounts visible to the current user.
• Tracking the active account in React state.
• Switching account context through application-defined transport.
• Composing account-aware application shells.

Install and compose

npm install @playstack/accounts @playstack/accounts-react react

Place the accounts provider inside the auth provider through a small application-owned bridge, so accounts stay optional and session replacement stays explicit:

import { PlaystackAccountsProvider, createFetchAccountsClient } from '@playstack/accounts-react'
import { useAuth, useSession } from '@playstack/auth-react'

const accountsClient = createFetchAccountsClient({
  baseUrl: 'https://api.example.com',
  headers: () => ({ authorization: `Bearer ${transport.getAccessToken()}` }),
})

function AccountsBridge({ children }) {
  const { session } = useSession()
  const { replaceSession, refresh } = useAuth()
  return (
    <PlaystackAccountsProvider
      client={accountsClient}
      session={session}
      onSessionChange={usesBearerTransport ? refresh : replaceSession}
    >
      {children}
    </PlaystackAccountsProvider>
  )
}

With the same-origin cookie transport, onSessionChange={replaceSession} adopts the session the switch returned. With the split-origin bearer transport, the API rotated the refresh cookie when it issued the account-scoped session, so pass refresh instead and the transport obtains the access token that matches the new session.

const { account, accounts, status, error, switchAccount, revalidate } = useAccount()

The provider clears account data when the authenticated user changes. Switching is allowed only to an account in the loaded list, and the returned session must match the same user, selected account, and listed role before state changes.

Provider properties

HTTP contract

The default client expects GET /api/accounts to return { accounts: AccountView[] } (id, name, slug, role) and POST /api/accounts/switch to accept { accountId } and return { session: AuthSessionView }. Configure baseUrl, accountsEndpoint, switchEndpoint, fetch and a headers callback: echo the CSRF cookie for same-origin cookie sessions, or supply the transport's bearer token for split-origin sessions. Requests include cookies. Account and response objects reject unknown fields and duplicate IDs, and valid { error: { code, retryable, message } } failures are preserved as AccountsClientError.remote.

Set sessionParser on both the client and the provider when sessions carry an application-validated extensions envelope; the default parser enforces the exact AuthSessionView projection and refuses extensions.

Boundary

The package does not authorize membership and deliberately does not depend on @playstack/auth-react. Server operations still validate account scope and role on every request.

API entry points and requirements

Reference snapshot: @playstack/accounts-react@0.1.0-beta.1. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.

Peer dependencies

Keep existing framework versions that satisfy these ranges. Install optional peers only when using the corresponding adapter. The package manager resolves ordinary dependencies separately.

For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.