@vtex/faststore-plugin-buyer-portal 2.0.8 → 2.0.9

package/docs/superpowers/specs/2026-06-26-contracts-listing-selection-search-pagination-design.md

@@ -0,0 +1,157 @@
+# Contracts listing — selection, search & local pagination
+
+**Date:** 2026-06-26
+**Status:** Approved (design)
+**Branch:** `feat/suma-switching`
+
+## Context
+
+The SUMA contracts listing (`ContractListingLayout`) shows all contracts for an org
+unit. We just wired clicking a contract to a real commercial-context switch
+(token/session change + navigation to the profile page).
+
+The problem: the **entire row** has a single `onClick` that triggers the switch, and the
+per-row checkbox is **display-only**. So clicking a checkbox switches contracts instead
+of selecting — the multi-select (future bulk-delete) feature is unusable. The reference
+screenshots also show a richer listing experience that isn't built yet: a search field,
+local pagination ("1 — 25 of 50" with prev/next arrows), a "Select all (N)" row with an
+indeterminate state, and a floating selection toolbar ("N selected" · ✕ · Remove).
+
+This change builds that full listing UX while preserving the contract-switch behavior.
+
+## Goals
+
+- Separate **checkbox click → select** from **row-body click → switch contract**.
+- Add **search** (local, case-insensitive over name/email).
+- Add **local pagination**: 25 per page, `<` / `>` arrows, `"{from} — {to} of {total}"`.
+- Add a **"Select all (N)"** row (tri-state: empty / indeterminate / checked) scoped to
+  **all filtered contracts** (across pages).
+- Add a **floating selection bar** ("N selected" · ✕ clear · **Remove**). Remove is a
+  **no-op placeholder** (bulk delete is a future feature).
+- Selection **persists** across search and page changes.
+
+## Non-goals
+
+- Implementing actual bulk contract removal (Remove stays a placeholder).
+- Server-side search/pagination (all contracts are already loaded client-side).
+- Changing the contract-switch flow itself (token/session) — already done.
+
+## Decisions (confirmed)
+
+| Question | Decision |
+| --- | --- |
+| Scope | Full listing UX from the screenshots |
+| Remove button | No-op placeholder |
+| Page size / control | 25 per page, prev/next arrows + interval counter |
+| Select-all scope | All filtered contracts; selection persists across pages/search |
+| Shift-range select | Keep, moved onto the checkbox |
+
+## Interaction model
+
+- **Checkbox click** → toggles that row's selection. Calls `stopPropagation()` so it
+  never triggers a switch. `event.shiftKey` → range select; otherwise plain toggle.
+- **Row body click** (avatar + name) → switches contract (existing `useSwitchContract`
+  flow). The `loading` guard and error toast stay.
+- The ⌘/Ctrl-click-on-row toggle is **removed** (selection now lives on the checkbox).
+- The ⌘/Ctrl + **A** keyboard select-all shortcut is **kept** (operates on filtered IDs).
+- Selection state is a `Set<string>` of contract IDs that survives filtering and paging.
+
+## Architecture
+
+All data is local — the layout already receives the full `contracts` array.
+
+### New hook: `useContractListing`
+`src/features/contracts/hooks/useContractListing.ts`
+- Input: `{ contracts: ContractData[]; pageSize?: number /* default 25 */ }`.
+- State: `searchTerm`, `page`.
+- Derived (via pure helpers, see below): `filtered`, `total`, `pageItems`, `from`, `to`,
+  `hasPrev`, `hasNext`, `filteredIds`.
+- Actions: `setSearch(term)` (resets `page` to 1), `nextPage()`, `prevPage()`.
+- Clamps `page` to valid range when the filtered set shrinks.
+
+### New pure helpers (testable in node env)
+`src/features/contracts/hooks/contractListingHelpers.ts`
+- `filterContracts(contracts, term)` — case-insensitive substring match on
+  `name ?? ""` and `email ?? ""`; empty/whitespace term returns all.
+- `paginate(items, page, pageSize)` → `{ pageItems, from, to, total, hasPrev, hasNext }`
+  (`from`/`to` are 1-based for display; `from = to = 0` when empty).
+
+### Reuse: `useContractSelection` (unchanged)
+`handleSelectAll(filteredIds)`, `handleModifierClick(id)` (toggle),
+`handleShiftClick(id, filteredIds)` (range), `clearSelection()`. Select-all and range are
+fed **`filteredIds`** (not just the current page).
+
+### Components
+- **`ContractListItem`** (edit) — checkbox is an interactive `role="checkbox"`
+  (`aria-checked`) element with `onClick` → `onSelect(id, event)` + `stopPropagation()`.
+  Row body retains the switch handler. New/changed props: replace
+  `onModifierClick`/`onShiftClick` with a single `onSelect(id, event)`; layout maps
+  `event.shiftKey ? handleShiftClick : handleModifierClick`.
+- **`ContractsListHeader`** (new) —
+  `src/features/contracts/components/ContractsListHeader/`. Left: `InternalSearch`
+  (`textSearch={setSearch}`, `defaultValue={searchTerm}`). Right: pagination control —
+  `"{from} — {to} of {total}"` and two icon-buttons (prev/next), disabled at the ends.
+- **`ContractSelectAllRow`** (new) —
+  `src/features/contracts/components/ContractSelectAllRow/`. Tri-state checkbox
+  (`checked` = all filtered selected, `indeterminate` = some, else empty) + label
+  `"Select all ({total})"`. Toggle: if any selected → `clearSelection()`, else
+  `handleSelectAll(filteredIds)`.
+- **`ContractSelectionBar`** (new) —
+  `src/features/contracts/components/ContractSelectionBar/`. Floating pill rendered when
+  `selectedIds.size > 0`: `✕` (→ `clearSelection`), `"{n} selected"`, `Remove` button
+  (red; **no-op** for now — `onClick={() => {}}` with a `// TODO: bulk delete` note).
+- **`ContractSelectionList`** (edit) — renders `pageItems` (not all contracts), forwards
+  `onSelect`. The old inline `[data-fs-bp-contract-selection-toolbar]` is removed in favor
+  of `ContractSelectionBar`.
+
+### Layout composition (`ContractListingLayout`, multi-contract branch)
+```
+<ContractsListHeader … />            // search + pagination
+<ContractSelectAllRow … />           // tri-state select all
+<ContractSelectionList items=pageItems onSelect … />
+<ContractSelectionBar selectedCount … onClear onRemove />  // floating, when selection > 0
+```
+The single-contract branch (BasicCard) is unchanged.
+
+## Styling
+
+Extend `contract-listing-layout.scss`:
+- `[data-fs-bp-contracts-list-header]` — flex row, search left / pagination right; arrow
+  icon-buttons with disabled state.
+- `[data-fs-bp-contract-select-all-row]` — checkbox + label row above the list.
+- Tri-state checkbox visuals (checked + indeterminate "minus"); reuse existing
+  `[data-fs-bp-contract-list-item-checkbox]` look, add an interactive/focus state.
+- `[data-fs-bp-contract-selection-bar]` — fixed, bottom-center, rounded, shadowed pill
+  (repurpose the removed toolbar's count/remove styles).
+
+## Icons
+
+Pagination arrows and the indeterminate "minus"/clear "✕" use `@faststore/ui`'s `Icon`
+(as `InternalSearch` does with `X` / `MagnifyingGlass`). Exact sprite symbol names
+(arrow-left/right, minus) verified against `/buyer-portal-icons.svg` and `@faststore/ui`
+during implementation; fall back to existing confirmed names if needed.
+
+## Testing
+
+- `contractListingHelpers.test.ts` (node env, pure functions):
+  - `filterContracts`: matches name and email case-insensitively; empty term → all;
+    no-match → empty.
+  - `paginate`: correct slice/from/to/hasPrev/hasNext for first/middle/last/empty pages;
+    page clamped past the end.
+- Existing `useContractSelection` helper tests still pass (toggle/range/select-all).
+- `make check` (lint + typecheck + test). Note: typecheck has ~133 pre-existing,
+  environment-related errors from the linked `@faststore/core`; the bar is **no new
+  errors in touched files**.
+
+## Manual verification (linked to `b2bfaststoredev.store`)
+
+1. Org unit with >25 contracts: list shows 25, counter `"1 — 25 of N"`, `>` enabled.
+2. Click `>` / `<` → page changes, counter updates, `<` disabled on page 1, `>` on last.
+3. Type in search → list filters live, resets to page 1, counter reflects filtered total.
+4. Click a **checkbox** → row selects, **no switch**; floating bar shows `"1 selected"`.
+5. Shift-click another checkbox → range selected.
+6. "Select all (N)" → all filtered selected (indeterminate when partial); ✕ clears.
+7. Selection persists when changing page / editing search.
+8. Click a **row body** (name) → contract switches (cookie/JWT changes, navigates to
+   profile) — unchanged from the prior change.
+9. Remove button is visible but does nothing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtex/faststore-plugin-buyer-portal",
-  "version": "2.0.8",
+  "version": "2.0.9",
   "description": "A plugin for faststore with buyer portal",
   "main": "index.js",
   "scripts": {

package/plugin.config.js

@@ -88,6 +88,14 @@ module.exports = {
       path: "/pvt/organization-account/accounting-field/[orgUnitId]/[contractId]/[accountingFieldId]",
       appLayout: false,
     },
+    contracts: {
+      path: "/pvt/organization-account/contracts/[orgUnitId]",
+      appLayout: false,
+    },
+    "contract-information": {
+      path: "/pvt/organization-account/contract-information/[orgUnitId]/[contractId]",
+      appLayout: false,
+    },
   },
 
   apis: {

package/public/buyer-portal-icons.svg

@@ -283,6 +283,28 @@
       d="M154-128q-43.72 0-74.86-31.14Q48-190.27 48-234v-492q0-43.72 31.14-74.86T154-832h220l106 106h326q43.72 0 74.86 31.14T912-620v386q0 43.73-31.14 74.86Q849.72-128 806-128H154Zm339.67-136 104.16-79.68L702-264l-38-130 104-84H638l-40-126-40 126H428l104.17 84.23L493.67-264Z" />
   </symbol>
 
+  <symbol
+    id="Star"
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 24 24"
+    fill="currentColor"
+  >
+    <path
+      d="M12 17.27L18.18 21l-1.64-7.03L22 9.24l-7.19-.61L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21z"
+      fill="currentColor" />
+  </symbol>
+
+  <symbol
+    id="StarOutline"
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 24 24"
+    fill="currentColor"
+  >
+    <path
+      d="M22 9.24l-7.19-.62L12 2 9.19 8.62 2 9.24l5.46 4.73L5.82 21 12 17.27 18.18 21l-1.63-7.03L22 9.24zM12 15.4l-3.76 2.27 1-4.28-3.32-2.88 4.38-.38L12 6.1l1.71 4.04 4.38.38-3.32 2.88 1 4.28L12 15.4z"
+      fill="currentColor" />
+  </symbol>
+
   <symbol id="LoadingIndicator" xmlns="http://www.w3.org/2000/svg"
     viewBox="0 0 18 18" fill="none">
     <path
@@ -606,4 +628,18 @@
       <path d="M24.771 32.622C24.9723 32.4213 25.073 32.1643 25.073 31.851C25.073 31.5377 24.9727 31.2803 24.772 31.079C24.5713 30.8777 24.3143 30.777 24.001 30.777C23.6877 30.777 23.4303 30.8773 23.229 31.078C23.0277 31.2787 22.927 31.5357 22.927 31.849C22.927 32.1623 23.0273 32.4197 23.228 32.621C23.4287 32.8223 23.6857 32.923 23.999 32.923C24.3123 32.923 24.5697 32.8227 24.771 32.622ZM23.304 26.4655H24.8425V14.1615H23.304V26.4655ZM24.02 42C21.514 42 19.1758 41.5277 17.0055 40.583C14.8348 39.6383 12.9307 38.348 11.293 36.712C9.65533 35.076 8.36383 33.1725 7.4185 31.0015C6.47283 28.8302 6 26.4902 6 23.9815C6 21.4985 6.47233 19.164 7.417 16.978C8.36167 14.7923 9.652 12.889 11.288 11.268C12.924 9.647 14.8275 8.36383 16.9985 7.4185C19.1698 6.47283 21.5098 6 24.0185 6C26.5015 6 28.836 6.47233 31.022 7.417C33.2077 8.36167 35.111 9.64367 36.732 11.263C38.353 12.8823 39.6362 14.7867 40.5815 16.976C41.5272 19.165 42 21.4997 42 23.98C42 26.486 41.5277 28.8242 40.583 30.9945C39.6383 33.1652 38.3563 35.0663 36.737 36.698C35.1177 38.3293 33.2133 39.6208 31.024 40.5725C28.835 41.5242 26.5003 42 24.02 42ZM24.025 40.4615C28.5877 40.4615 32.4678 38.8608 35.6655 35.6595C38.8628 32.4582 40.4615 28.5633 40.4615 23.975C40.4615 19.4123 38.866 15.5322 35.675 12.3345C32.4837 9.13717 28.592 7.5385 24 7.5385C19.4283 7.5385 15.5418 9.134 12.3405 12.325C9.13917 15.5163 7.5385 19.408 7.5385 24C7.5385 28.5717 9.13917 32.4582 12.3405 35.6595C15.5418 38.8608 19.4367 40.4615 24.025 40.4615Z" fill="currentColor"/>
     </g>
   </symbol>
-</svg>
+  <symbol
+    id="Sparkle"
+    viewBox="0 -960 960 960"
+    fill="currentColor"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <path fill="currentColor"
+      d="M480-80q0-83-31.5-156T363-363q-54-54-127-85.5T80-480q83 0 156-31.5T363-597q54-54 85.5-127T480-880q0 83 31.5 156T597-597q54 54 127 85.5T880-480q-83 0-156 31.5T597-363q-54 54-85.5 127T480-80Z" />
+  </symbol>
+  <symbol id="InfoSolid" xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 256 256"
+    fill="currentColor">
+      <path d="M128,24A104,104,0,1,0,232,128,104.11,104.11,0,0,0,128,24Zm-4,48a12,12,0,1,1-12,12A12,12,0,0,1,124,72Zm12,112a16,16,0,0,1-16-16V128a8,8,0,0,1,0-16,16,16,0,0,1,16,16v40a8,8,0,0,1,0,16Z" fill="currentColor"></path>
+  </symbol>
+</svg>

package/specs/001-suma-phase-2/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: SUMA Phase 2 — Contract Listing, Switching & Management
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-06-15
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- All checklist items pass. Spec is ready for `/speckit-plan`.
+- Session integration with Identity/Auth team is flagged as an assumption — confirm before coding begins.
+- UX prototype approval is assumed; verify no late-breaking changes before implementation.

package/specs/001-suma-phase-2/contracts/contracts-api.md

@@ -0,0 +1,187 @@
+# BFF API Contract: Contracts Domain
+
+**Feature**: SUMA Phase 2  
+**Date**: 2026-06-15  
+**Updated**: 2026-06-18 (confirmed BFF v1.0.3; activate endpoint removed — not a BFF concept)  
+**Base path**: `/_v/store-front/` (via `getApiUrl()` — see `src/features/shared/utils/constants.ts`)
+
+All storefront endpoints are relative to this base. The client (`ContractsClient.ts`) uses paths like `units/{orgUnitId}/contracts/attached` which expand to `/_v/store-front/units/{orgUnitId}/contracts/attached`.
+
+---
+
+## Existing Endpoints (no changes needed)
+
+### Get Contract Details
+
+```
+GET  units/{orgUnitId}/contracts/{contractId}
+Auth: Cookie header
+
+Response 200:
+{
+  contract: ContractData
+}
+```
+
+### Toggle Contract Active Status
+
+```
+POST  units/{unitId}/contracts/{contractId}/status
+Auth: Cookie header
+Body: { isActive: boolean }
+
+Response 200:
+{ isActive: boolean }
+
+Note: Toggles whether a contract is enabled in the unit.
+      Distinct from contract switching (session scope).
+```
+
+---
+
+## Storefront Endpoints — BFF v1.0.2 (Confirmed)
+
+These replace the previously speculative SUMA Phase 2 endpoints.
+
+### List Attached Contracts
+
+```
+GET  units/{orgUnitId}/contracts/attached
+GET  units/{orgUnitId}/contracts/attached?details=true  ← include full contract objects
+Auth: Cookie header
+
+Response 200 (without ?details):
+{
+  contractIds: string[]
+}
+
+Response 200 (with ?details=true):
+{
+  contracts: ContractData[]
+}
+
+Note: Returns contracts within this unit's contractIds scope.
+```
+
+### List Available Contracts
+
+```
+GET  units/{orgUnitId}/contracts/available
+Auth: Cookie header
+
+Response 200:
+{
+  contractIds: string[]
+}
+
+Note: Returns the allowed contract ID list from the org root unit's
+      contractIds scope — i.e., the superset a child unit can attach from.
+```
+
+### Add Contracts to Unit
+
+```
+POST  units/{orgUnitId}/contracts/attached
+Auth: Cookie header
+Body: {
+  ids: string[]
+}
+
+Constraints:
+  - IDs must be within the root unit's contractIds scope (available contracts)
+  - Cap: max 20 IDs per unit total after merge
+
+Response 200:
+{ ... }   ← shape TBD; confirm with BFF team
+
+Frontend behavior:
+  - Success → refresh attached contracts list
+  - Error   → show error toast
+```
+
+### Remove One Contract from Unit
+
+```
+DELETE  units/{orgUnitId}/contracts/attached/{contractId}
+Auth: Cookie header
+
+Note: Per-resource deletion (one contract at a time).
+      For bulk removal, call in sequence for each contractId.
+
+Response 200 / 204:
+(empty or minimal confirmation)
+
+Frontend guards (enforced before calling):
+  - Cannot remove if resulting count would be 0 (UI blocks)
+  - Remove option hidden when unit has exactly 1 contract
+```
+
+---
+
+## Management Endpoints — BFF v1.0.2 (Admin-Only)
+
+These use a **different base path** (`/_v/contracts-management/`) and are not reachable
+via the standard `ContractsClient` which targets `/_v/store-front/`.
+
+A separate client (e.g., `ContractsManagementClient`) with a custom URL is required.
+
+```
+GET     /_v/contracts-management/unit-contracts/{unitId}
+POST    /_v/contracts-management/unit-contracts/{unitId}   Body: { ids: string[] }
+DELETE  /_v/contracts-management/unit-contracts/{unitId}/{contractId}
+```
+
+These are admin-only maintenance operations for the root unit `contractIds` scope.
+The storefront endpoints (above) are used by buyers and respect the scope set here.
+
+---
+
+## TBD Endpoints (Not yet confirmed)
+
+| Operation                          | Original speculative path                               | Status                                                                                                                                                                                                                                                                       |
+| ---------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Activate contract (switch session) | —                                                       | **Not a BFF concept.** In SUMA, "navigating to a contract" is purely client-side routing (`router.push`). No BFF call needed. Confirmed after checking BFF v1.0.3 routes and clarifying the SUMA mental model: same user, multiple contracts, all simultaneously accessible. |
+| Set default contract               | `POST units/{orgUnitId}/contracts/{contractId}/default` | TBD — pending BFF team confirmation. Frontend renders the "Set as default" menu item as disabled until this is confirmed.                                                                                                                                                    |
+
+---
+
+## Frontend Client Methods to Add
+
+These map to new methods in `src/features/contracts/clients/ContractsClient.ts`:
+
+```typescript
+// List contracts in the unit's attached scope (with optional inline details)
+listAttachedContracts(orgUnitId: string, cookie: string, details?: boolean)
+  → Promise<{ contractIds: string[] } | { contracts: ContractData[] }>
+
+// List contracts available to attach (from root unit scope)
+listAvailableContracts(orgUnitId: string, cookie: string)
+  → Promise<{ contractIds: string[] }>
+
+// Add contracts to unit scope (max 20 total; must be within root scope)
+addContracts(orgUnitId: string, ids: string[], cookie: string)
+  → Promise<unknown>   // shape TBD
+
+// Remove one contract from unit scope (call per contractId for bulk)
+removeContract(orgUnitId: string, contractId: string, cookie: string)
+  → Promise<void>
+```
+
+---
+
+## Page Routes (Frontend)
+
+| Page                 | Route                                                                     | File                                 |
+| -------------------- | ------------------------------------------------------------------------- | ------------------------------------ |
+| Contract Listing     | `/pvt/organization-account/contracts/[orgUnitId]`                         | `src/pages/contracts.tsx`            |
+| Contract Information | `/pvt/organization-account/contract-information/[orgUnitId]/[contractId]` | `src/pages/contract-information.tsx` |
+
+Both registered in `plugin.config.js` and exposed via `buyerPortalRoutes.ts`:
+
+```typescript
+contracts: (params: { orgUnitId: string }) =>
+  replaceParams(`${base}/contracts/[orgUnitId]`, params),
+
+contractInformation: (params: { orgUnitId: string; contractId: string }) =>
+  replaceParams(`${base}/contract-information/[orgUnitId]/[contractId]`, params),
+```

package/specs/001-suma-phase-2/contracts/feature-flag.md

@@ -0,0 +1,91 @@
+# Feature Flag Contract: suma
+
+**Feature**: SUMA Phase 2  
+**Date**: 2026-06-15  
+**Updated**: 2026-06-17
+
+---
+
+## Flag Definition
+
+| Property | Value |
+|----------|-------|
+| FeatureHub key | `suma` |
+| BFF constant array | `BUYER_PORTAL_FEATURE_FLAGS` in `flags.constants.ts` |
+| Frontend TypeScript property | `suma?: boolean` |
+| Type | Boolean (Standard Flag) |
+| Default (flag off) | `false` — original navigation preserved |
+
+---
+
+## Behavior
+
+| Flag state | Homepage redirect target | Navigation |
+|------------|-------------------------|-----------|
+| `false` (off) | `org-unit-details` (existing behavior) | Unchanged |
+| `true` (on) | `contracts` (Contract Listing — new) | SUMA Phase 2 flows active |
+
+---
+
+## Where to Update
+
+### 1. BFF (not in this repo)
+
+```typescript
+// buyer-portal-graphql/node/modules/flags/flags.constants.ts
+export const BUYER_PORTAL_FEATURE_FLAGS = [
+  'enable_alternative_login',
+  'suma',   // ADD
+] as const;
+```
+
+### 2. Frontend type definition
+
+```typescript
+// src/features/shared/components/BuyerPortalProvider/BuyerPortalProvider.tsx
+export type FeatureFlags = {
+  enableAlternativeLogin?: boolean;
+  authSettings?: AuthSettingsFeatureFlags;
+  suma?: boolean;   // ADD
+};
+```
+
+### 3. Flag normalization in get-feature-flags.service.ts
+
+The flag key `suma` matches the TypeScript property name directly — no snake_case → camelCase conversion needed. Add it to `getBuyerPortalFeatureFlags()`:
+
+```typescript
+// src/features/shared/services/feature-flags/get-feature-flags.service.ts
+export async function getBuyerPortalFeatureFlags(cookie: string): Promise<FeatureFlags> {
+  const raw = await fetchBuyerPortalFlags(cookie);
+  const normalized = normalizeFlagsEndpointBooleans(raw);
+
+  return {
+    enableAlternativeLogin: normalized["enable_alternative_login"] ?? false,
+    authSettings: parseAuthSettingsFromFlags(raw),
+    suma: normalized["suma"] ?? false,   // ADD
+  };
+}
+```
+
+### 4. Usage in home.tsx
+
+```typescript
+// src/pages/home.tsx — conditional redirect
+if (featureFlags?.suma) {
+  // redirect to contracts listing
+  Location: buyerPortalRoutes.contracts({ orgUnitId: userOrgUnit.id })
+} else {
+  // existing redirect
+  Location: buyerPortalRoutes.orgUnitDetails({ orgUnitId: userOrgUnit.id })
+}
+```
+
+---
+
+## Rollout Plan
+
+1. Create flag in FeatureHub dashboard under the Organization Account project with key `suma`
+2. Enable in `dev` environment for testing
+3. Enable in `prod` behind a % rollout after E2E validation
+4. Full enable after stakeholder sign-off

package/specs/001-suma-phase-2/data-model.md

@@ -0,0 +1,119 @@
+# Data Model: SUMA Phase 2
+
+**Feature**: Contract Listing, Switching & Management  
+**Date**: 2026-06-15
+
+---
+
+## Entities
+
+### ContractData (extended)
+
+The existing type extended with SUMA Phase 2 fields.
+
+**File**: `src/features/contracts/types/ContractData.ts`
+
+```
+ContractData {
+  id: string                        -- unique identifier (from BFF)
+  name: string | null               -- display name; fall back to email if null
+  email: string                     -- contact email for the contract
+  isActive: boolean                 -- whether the contract is enabled in this org unit
+  isDefault?: boolean               -- NEW: whether this is the unit's default contract
+  creationDate: string              -- ISO date string
+  salesRepresentative?: string      -- optional
+  imageUrl?: string                 -- optional logo/image
+  assortment?: unknown[]            -- optional, opaque
+}
+```
+
+**Validation rules**:
+- `id` must be non-empty
+- `isDefault` defaults to `false` when absent (treat as optional for backward compat)
+- At most one contract per org unit may have `isDefault: true`
+
+**State transitions** (from Contract Listing perspective):
+
+```
+Contract states:
+  active (session) ← activate() → inactive
+  default          ← setDefault() → non-default
+
+  Multi-select states:
+  unselected → selected (via click modifiers) → unselected
+```
+
+---
+
+### ActiveContract (session concept)
+
+Not a stored entity — derived from session. Represents which contract the current user's session is scoped to.
+
+```
+ActiveContract {
+  contractId: string     -- ID of the currently active contract
+  orgUnitId: string      -- ID of the org unit
+}
+```
+
+**Lifecycle**:
+1. Loaded from session on page load (provided via `BuyerPortalContext`)
+2. Updated via BFF `activate` call
+3. Broadcast to other tabs via `BroadcastChannel` after successful activation
+
+---
+
+### ContractSelection (UI state — not persisted)
+
+Managed by `useContractSelection` hook. Not stored in BFF or localStorage.
+
+```
+ContractSelection {
+  selectedIds: Set<string>       -- set of selected contract IDs
+  lastSelectedIndex: number      -- index of last Shift+Click anchor (for range selection)
+}
+```
+
+**Transitions**:
+- `handleSelectAll(ids)`: replace `selectedIds` with all provided IDs
+- `handleModifierClick(id)`: toggle `id` in `selectedIds`
+- `handleShiftClick(id, allIds)`: fill range from `lastSelectedIndex` to target index
+- `clearSelection()`: empty `selectedIds`
+
+---
+
+### OrgUnitBasicData (existing — relevant subset)
+
+```
+OrgUnitBasicData {
+  id: string
+  name: string
+  parentId?: string     -- enables hierarchy navigation
+  children?: OrgUnitBasicData[]
+}
+```
+
+No changes needed. Used by `OrgUnitBreadcrumb` for hierarchy navigation.
+
+---
+
+## Relationships
+
+```
+OrgUnit 1 ──────────── * ContractData
+                        │
+                        ├── 0..1 isDefault: true
+                        └── 0..1 isActive (session)
+
+ContractData * ──────── * OrgUnit (via propagate-to-children)
+```
+
+A single org unit holds many contracts. Exactly one may be the `isDefault`. The session's active contract is tracked separately as `ActiveContract`.
+
+---
+
+## Feature Flag
+
+**Key** (BFF / FeatureHub): `enable_suma_phase_2`  
+**TypeScript property**: `enableSumaPhase2?: boolean` (added to `FeatureFlags` in `BuyerPortalProvider.tsx`)  
+**Effect when true**: home page redirects to Contract Listing instead of org-unit-details