Breaking Changes

SessionStore.setSession is now optional

// Before — no-op workaround (caused silent logout bug)
createCoinListServer({
  sessionStore: {
    getSession: () => getServerSession(),
    setSession: async () => {}, // ← remove this
  },
});

// After — read-only store (safe, explicit)
createCoinListServer({
  sessionStore: {
    getSession: () => getServerSession(),
  },
});

Added

WritableSessionStoreRequiredError

Fixed

No unnecessary network retries on expired tokens in read-only mode

Breaking Changes

Client methods renamed: fetchAll* → fetch*

fetchAllOffers(    →  fetchOffers(
fetchAllParticipations(  →  fetchParticipations(

Hooks renamed: useCoinList* → use*

// Before
import { useCoinListOffers, useCoinListRequirements } from '@coinlist-co/react';
const { offersState } = useCoinListOffers({ serverOffers: data });

// After
import { useOffers, useRequirements } from '@coinlist-co/react';
const { offersState } = useOffers({ data });

SSR prop renamed: serverOffers / serverData → data

LoadRequirementsState CONTENT shape: requirementsByOptionId → requirements

// Before
if (requirementsState.type === 'CONTENT') {
  const byOption = requirementsState.requirementsByOptionId;
}

// After
if (requirementsState.type === 'CONTENT') {
  const byOption = requirementsState.requirements;
}

Base* components removed

Import paths restructured — new @coinlist-co/react/shared entry point

// Before (sub-path imports — no longer valid)
import { CoinListClient } from '@coinlist-co/react/client';
import { useOffers } from '@coinlist-co/react/client/hooks';

// After
import { CoinListClient, useOffers } from '@coinlist-co/react';

OffersGridProps type renamed from Props

// Before
import type { Props } from '@coinlist-co/react';

// After
import type { OffersGridProps } from '@coinlist-co/react';

Added

Server (@coinlist-co/react/server)

• CoinListServer now exposes the full data-fetching surface previously only available on CoinListClient: fetchAllOffers(), fetchOffersPage(), fetchOfferDetails(), fetchAllParticipations(), fetchParticipationsPage(), fetchParticipation(), createParticipation(), fetchOfferRequirements(), and fetchRequirementStatuses(). Use these in Next.js Route Handlers and Server Components without shipping any client bundle.
• @coinlist-co/react/server now re-exports all shared types — Offer, OfferDetail, Participation, Requirement, RequirementStatusInfo, pagination helpers, NotAuthenticatedError, and related types — so you no longer need to import them from the client entry.

Client (@coinlist-co/react, @coinlist-co/react/client)

• useParticipations(offerId?) hook — loads all participations for the authenticated user with a LOADING / CONTENT / ERROR state machine, optionally filtered by offer. New exported types: UseParticipationsResult, LoadParticipationsState, LoadParticipationsReason.
• handleRequirement(requirement) on CoinListClient — opens the corresponding CoinList page for completing a requirement in a new tab (/verify-identity, /wallet, etc.). No-op for jurisdiction requirements.
• contactSupport() on CoinListClient — opens the CoinList support ticket page in a new tab.

Changed

Components

• RequirementsChecklist: onRequirementAction and onContactSupport props have been renamed to onRequirementActionOverride and onContactSupportOverride. Both now default to CoinListClient#handleRequirement and CoinListClient#contactSupport respectively, so most integrations can omit them entirely. Pass null to disable the corresponding button/link.
• RequirementItem: onAction and onContactSupport now accept null (in addition to undefined) to suppress rendering of action buttons.

Removed

Client (@coinlist-co/react, @coinlist-co/react/client)

• sandbox option removed from ClientConfig. Sandbox offers are no longer toggled via the SDK config.
• StaticRequirementsChecklistProps type removed. Use RequirementsChecklist with the connected API or BaseRequirementsChecklist for fully custom rendering.

Added

Client (@coinlist-co/react, @coinlist-co/react/client)

• fetchOfferRequirements(offerId) on CoinListClient — returns requirements grouped by option ID (Record<OfferOptionId, Requirement[]>).
• fetchRequirementStatuses(offerId) on CoinListClient — returns the authenticated user’s status for each requirement.
• useCoinListRequirements(offerId) hook for loading requirements and statuses with a LOADING / CONTENT / ERROR state machine.
• sandbox option on ClientConfig — when true, passes sandbox=true to offers API calls so sandbox offers are included.
• New exported types: Requirement, RequirementId, RequirementType, RequirementStatusValue, RequirementStatusInfo, ParticipationsPaginationParams.
• New exported enums/constants: RequirementVariant, RequirementStatus, ChecklistStatus.
• New hook types: UseCoinListRequirementsResult, LoadRequirementsState, LoadRequirementsReason.
• fetchAllParticipations(offerId?) and fetchParticipationsPage(params) now accept an optional offerId to fetch participations for a specific offer. fetchParticipationsPage takes the new ParticipationsPaginationParams type (superset of PaginationParams) which carries the offerId field.

Fixed

Components

• Fixed missing dark mode CSS variables in Next.js projects — prebuilt styles now include the full set of design-system tokens so components render correctly under dark class or prefers-color-scheme: dark.

Added

Client (@coinlist-co/react, @coinlist-co/react/client)

• fetchAllParticipations() on CoinListClient for fetching all participations across pages.
• fetchParticipationsPage() on CoinListClient for paginated participation fetching.
• fetchParticipation() on CoinListClient for fetching a single participation by id.
• createParticipation() on CoinListClient for creating a new participation.
• New exported types: Participation, ParticipationId, ParticipationStatus, CreateParticipationParams, Blockchain, WalletAddress.

Added

Client (@coinlist-co/react, @coinlist-co/react/client)

• Added support for passing className and containerClassName to <OffersGrid />, <OfferCard />, and <CoinListSignInCard />.

Fixed

Client (@coinlist-co/react, @coinlist-co/react/client)

• Re-export offer, offer detail, and pagination types from the package root and client core entry so you can type against Offer, OfferDetail, pagination params, and related helpers without reaching into internal modules.
• Export BaseCoinListSignInCard and BaseCoinListSignInCardProps from @coinlist-co/react/client for custom sign-in layouts built on the same primitives as CoinListSignInCard.

Added

Client (@coinlist-co/react/client)

• fetchAllOffers(), fetchOffersPage(), and fetchOfferDetails() on CoinListClient for fetching offers data.
• <OffersGrid /> — batteries-included component that loads offers and displays them in a responsive grid, with <OfferCard /> for each tile.
• useCoinListOffers() hook for loading offers when you want full control over layout instead of the grid.
• useCoinListOfferDetails() hook for a single offer’s details.
• useCompleteCoinListOAuth() hook to run the OAuth redirect callback once on mount.
• Optional authorizationPageUrl on client config so you can point startOAuth() at a non-production authorization page.

Added

Client (@coinlist-co/react/client)

• CoinListProvider and useCoinList() hook for React context-based SDK initialization.
• createCoinListClient(config) factory for manual or non-React usage.
• OAuth 2.0 with PKCE via startOAuth() and completeOAuth().
• getAuthState() and logout().

Server (@coinlist-co/react/server)

• createCoinListServer(config) factory for BFF / Next.js API routes.
• completeOAuth(), accessToken() (auto-refreshing), and logout().

Components

• CoinListSignInCard and CoinListSignInButton for OAuth sign-in flows.
• RequirementsChecklist / RequirementItem — eligibility checklist with accordion UI.
• PoweredByCoinList attribution badge.
• Prebuilt CSS — no tailwindcss peer dependency required.

Infrastructure

• Subpath exports: @coinlist-co/react, @coinlist-co/react/client, @coinlist-co/react/server.
• Requires React 18+.