woodsportal-client-sdk 1.1.4 → 2.0.705

package/CHANGELOG.md

@@ -5,10 +5,138 @@ All notable changes to **woodsportal-client-sdk** are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.1.2] - 2026-08-14
+
+### Fixed
+
+- Block HTTP requests whose URL contains unresolved id segments (`undefined` / `null` / `NaN`).
+- When the embedding page CSP blocks API calls, log the violated directive and the fix to apply.
+
+## [4.1.0] - 2026-08-06
+
+### Added
+
+- CRM request payload helpers to resolve path vs query params for list/details/association flows.
+- `selectedStage` LIST filter support and related board/list stage URL handling.
+
+### Fixed
+
+- Association / primary-company list params (`isPrimaryCompany`) and ticket LIST stage leakage across tabs.
+- Admin locked pipeline treated as selected for LIST filters; `setSelectedStage` no-op when unchanged.
+
+## [4.0.0] - 2026-06-06
+
+### Removed (breaking)
+
+- **`state/legacy/`** — legacy table UI store (`use-table-ui`, `create-store`, `table-stores`, `resolve-table-list-params`).
+- **Flat root `api.*` shims** — only `api.auth`, `api.crm`, `api.navigation` remain.
+- **Top-level navigation exports** — `url`, `routeParam`, `breadcrumbsDetails` (use `api.navigation.*`).
+- **`config` export** — use `hubContext` / `setHubContext`.
+- **`store.useTable` / `store.legacyTableUi`** — use `store.tableUi` or `useTableUi()` from framework adapters.
+
+### Changed (breaking)
+
+- **Table UI state:** canonical `state/crm/table-ui.ts` + `table-ui-actions.ts`; reactive hook **`useTableUi()`** (replaces `useLegacyTableUi`).
+- **List mutations:** `api.crm.objects.list()` and `api.crm.pipelines.list()` **require** `payload.tableParams` (no global store fallback).
+- **`setObjectsData`** accepts `{ stageId }` from resolved list params (board append no longer reads global legacy store).
+
+### Added
+
+- `store.tableUi: { store, actions }` on root `store` export.
+- `features/crm/helpers/normalize-table-list-params.ts` — validates required `tableParams`.
+- Tests updated for nested-only API surface.
+
+### Migration (3.x → 4.0)
+
+| 3.x | 4.0 |
+|-----|-----|
+| `useLegacyTableUi()` | `useTableUi()` |
+| `store.legacyTableUi()` | `store.tableUi.actions` / `useTableUi()` |
+| `api.login()` | `api.auth.login()` |
+| `url.makeLink()` | `api.navigation.url.makeLink()` |
+| `list({ hubspotObjectTypeId })` | `list({ hubspotObjectTypeId, tableParams: getTableParam() })` |
+
+See [docs/PUBLIC-API-NAMING.md](docs/PUBLIC-API-NAMING.md).
+
+## [3.0.0] - 2026-06-06
+
+### Changed (breaking)
+
+- **Nested public API:** `api.auth`, `api.crm`, `api.navigation` replace the flat `api.*` spread as the canonical surface. See [docs/PUBLIC-API-NAMING.md](docs/PUBLIC-API-NAMING.md).
+- **Mutation aliases:** primary alias matches nested leaf (`api.crm.objects.list()` → `{ list, mutate, isLoading }`).
+- **Session helpers:** `api.auth.session.isAuthenticated()`, `refreshAccessToken()`, `isAccessTokenExpired()` (flat names deprecated).
+- **Profile update:** nested key `api.auth.updateProfile()` (was `profileUpdate`).
+- **Store:** `store.legacyTableUi` (was `store.useTable` — shim retained until 4.0).
+- **Hub context:** prefer `hubContext` export; `config` deprecated.
+
+### Added
+
+- [docs/PUBLIC-API-NAMING.md](docs/PUBLIC-API-NAMING.md) — full 2.x→3.x migration matrix.
+- `src/test/apis/nested-api.test.ts`, `flat-api-governance.test.ts` — nested paths + shim registry guards.
+- Concurrent `me()` dedup (in-flight share).
+
+### Deprecated (remove in 4.0)
+
+- Flat root `api.*` keys (`api.objects`, `api.login`, …) — delegate to nested paths.
+- Top-level `url`, `routeParam`, `breadcrumbsDetails` — use `api.navigation.*`.
+- `store.useTable`, `config` export.
+
+### Migration
+
+See [docs/PUBLIC-API-NAMING.md](docs/PUBLIC-API-NAMING.md) for the full table. Examples:
+
+| 2.x | 3.0 |
+|-----|-----|
+| `api.login()` | `api.auth.login()` |
+| `api.objects()` / `{ getObjects }` | `api.crm.objects.list()` / `{ list }` |
+| `api.getAccessToken()` | `api.auth.session.getAccessToken()` |
+| `url.makeLink()` | `api.navigation.url.makeLink()` |
+
+## [2.0.0] - 2026-06-05
+
+### Changed (breaking)
+
+- **Folder structure:** layered layout — `core/`, `features/auth|crm|navigation`, `state/crm/`. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+- **Subpath entries:** `woodsportal-client-sdk/auth` and `/crm` no longer re-import the monolithic `index.ts` graph.
+- **Navigation URL helpers:** `url.useMakeLink` → `url.makeLink`, `url.useUpdateLink` → `url.updateLink` (factory functions; not React hooks).
+
+### Removed (breaking)
+
+- `clint` namespace export
+- `http-clint.ts`, `localStoraget.ts` typo shims
+- `routing/route-param.ts` (use `routeParam` from main or `/crm` entry)
+
+### Migration
+
+| Before (1.x)                                          | After (2.0)                  |
+| ----------------------------------------------------- | ---------------------------- |
+| `url.useMakeLink()`                                   | `url.makeLink()`             |
+| `url.useUpdateLink()`                                 | `url.updateLink()`           |
+| `import … from 'woodsportal-client-sdk'` (deep paths) | Use documented subpaths only |
+| `clint`                                               | `Client` from main export    |
+
+### Added
+
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md)
+- CRM entry bundle budget in `npm run size:check`
+- `examples/smoke-consumer/smoke-auth-only.mjs` — auth subpath isolation smoke
+
 ## [Unreleased]
 
 ### Added
 
+- **Client-lane MFA APIs:** `verifyOtp`, `sendMfaOtp`, pending passkey MFA step, enrollment (TOTP, phone verify, WebAuthn/passkeys), passwordless passkey login, and `getMfaStatus` / `setMfaPreferences`.
+- **Client-lane security settings APIs:** `getSecurityOverview`, `getSecurityLoginActivity`, `getSecuritySessions`, `revokeSecuritySession`, `revokeOtherSecuritySessions`.
+- **MFA-aware login:** `api.login()` stores only the temp access JWT when `twoFactorRequired` is true (no refresh token until MFA completes).
+- Exported TypeScript types for MFA and security DTOs (`MfaMethod`, `SecurityOverview`, `ActiveSession`, etc.).
+- **Docs:** [`docs/MFA-SECURITY-SDK.md`](docs/MFA-SECURITY-SDK.md) — full SDK method → API reference with examples; JSDoc on all MFA/security facades for IDE hover.
+
+### Changed
+
+- **Source layout:** production code under `src/main/`, unit tests under `src/test/` (Spring Boot / Maven mirror). Update local imports or docs that referenced `src/` directly.
+
+### Added
+
 - **`formatHubSpotActivityDateTime`**, **`formatHubSpotActivityDateTimeParts`**, **`formatGmtOffset`**, **`normalizeToTimestamp`**, and **`DEFAULT_HUBSPOT_TIMEZONE`** (`Asia/Kolkata`) for HubSpot-style activity timestamps (e.g. `May 27, 2026 at 11:31 PM GMT+5:30`).
 
 ### Added

package/README.md

@@ -2,13 +2,32 @@
 
 TypeScript/JavaScript **ESM** client for the **WoodsPortal** HTTP API: authentication, SSO, users, pipelines, HubSpot-aligned objects, notes, emails, uploads, and files.
 
-| | |
-|---|---|
-| **npm** | [`woodsportal-client-sdk`](https://www.npmjs.com/package/woodsportal-client-sdk) |
-| **Source** | [`Digital-Woods/digitalwoods.io-woodsportal-client-sdk`](https://github.com/Digital-Woods/digitalwoods.io-woodsportal-client-sdk) |
-| **Issues** | [GitHub Issues](https://github.com/Digital-Woods/digitalwoods.io-woodsportal-client-sdk/issues) |
-| **Runtime** | Node **≥ 18**; **ESM only** (`"type": "module"` in consuming apps is recommended) |
-| **License** | **ISC** — see [`LICENSE`](./LICENSE) |
+|             |                                                                                                                                   |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| **npm**     | [`woodsportal-client-sdk`](https://www.npmjs.com/package/woodsportal-client-sdk)                                                  |
+| **Source**  | [`Digital-Woods/digitalwoods.io-woodsportal-client-sdk`](https://github.com/Digital-Woods/digitalwoods.io-woodsportal-client-sdk) |
+| **Issues**  | [GitHub Issues](https://github.com/Digital-Woods/digitalwoods.io-woodsportal-client-sdk/issues)                                   |
+| **Runtime** | Node **≥ 18**; **ESM only** (`"type": "module"` in consuming apps is recommended)                                                 |
+| **License** | **ISC** — see [`LICENSE`](./LICENSE)                                                                                              |
+
+---
+
+## Project layout (Spring Boot–style)
+
+Production and test sources are split like WoodsPortal Java services:
+
+| Path        | Role                                                                                                              |
+| ----------- | ----------------------------------------------------------------------------------------------------------------- |
+| `src/main/` | Library source — `core/`, `features/`, `state/`, `adapters/` (see [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)) |
+| `src/test/` | Unit tests mirroring `src/main/` package paths                                                                    |
+
+Example: `src/main/client/auth-headers.ts` ↔ `src/test/client/login-session.test.ts`.
+
+See [`src/test/README.md`](src/test/README.md). Run tests with `npm test`.
+
+**Contributors:** [docs/DEVELOPER-GUIDE.md](./docs/DEVELOPER-GUIDE.md) · [CONTRIBUTING.md](./CONTRIBUTING.md)
+
+Monorepo watch rebuild: `yarn local` (or `npm run local`) in this repo — same script name as client/admin, but **library watch only** (no Vite dev server). See the developer guide for the two-terminal workflow.
 
 ---
 
@@ -19,7 +38,7 @@ TypeScript/JavaScript **ESM** client for the **WoodsPortal** HTTP API: authentic
 3. **Use HTTPS** for `baseURL` in every deployed environment.
 4. **Do not log** passwords, refresh tokens, access tokens, or full API error bodies in production telemetry.
 5. **Handle errors** with `try/await catch` around `mutate()`, and map user-visible text with **`getFormErrors`** / **`getFieldErrors`** when the API returns validation payloads.
-6. **Align hub context** with how your shell stores HubSpot data (`utils/config.ts` reads hub / dev-portal identifiers from app storage).
+6. **Align hub context** with how your shell stores HubSpot data (`core/utils/hub-context.ts` reads hub / dev-portal identifiers from app storage).
 
 ---
 
@@ -42,70 +61,97 @@ The SDK uses one shared Axios instance. If **`initializeHttpClient` has never be
 Call **`initializeHttpClient` once** during application bootstrap (before any `api.*` calls):
 
 ```typescript
-import { initializeHttpClient } from "woodsportal-client-sdk";
+import { initializeHttpClient } from 'woodsportal-client-sdk'
 
 initializeHttpClient({
-  baseURL: process.env.VITE_API_BASE_URL!, // example: Vite — use your env mechanism
-  timeout: 50_000,
-  hubId: process.env.VITE_HUB_ID,
-  devPortalId: process.env.VITE_DEV_PORTAL_ID,
-  skipCurrentPublicPath: () => false,
-  routes: {
-    unauthorized: "/unauthorized",
-    login: "/login",
-  },
-  onLogout: async () => {
-    // Clear cookies / storage and route to login — implementation is app-specific
-  },
-});
+    baseURL: process.env.VITE_API_BASE_URL!, // example: Vite — use your env mechanism
+    timeout: 50_000,
+    hubId: process.env.VITE_HUB_ID,
+    devPortalId: process.env.VITE_DEV_PORTAL_ID,
+    skipCurrentPublicPath: () => false,
+    routes: {
+        unauthorized: '/unauthorized',
+        login: '/login'
+    },
+    onLogout: async () => {
+        // Clear cookies / storage and route to login — implementation is app-specific
+    }
+})
 ```
 
-Hub and dev-portal identifiers are **also** read from browser storage in `src/utils/config.ts`. Keep that storage in sync with your HubSpot / portal shell so authenticated routes resolve the correct tenant context.
+Hub and dev-portal identifiers are **also** read from browser storage in `core/utils/hub-context.ts`. Keep that storage in sync with your HubSpot / portal shell so authenticated routes resolve the correct tenant context.
 
 ---
 
-## Public API
+## Public API (3.0)
 
-| Export | Purpose |
-|--------|---------|
-| **`api`** | Auth, SSO, users, pipelines, objects, notes, emails, uploads, files, token helpers. |
-| **`store`** | `storage` helpers and **`useTable`** (table state; name is historical — not a React hook). |
-| **`url`** | **`useMakeLink`**, **`useUpdateLink`** — breadcrumb / URL helpers (not React hooks). |
-| **`routeParam`** | **`getRouteDetails`**, **`getParamDetails`**. |
-| **`breadcrumbsDetails`** | **`getBreadcrumbs`**, **`getTableTitle`**, **`getFormTitle`**. |
-| **`initializeHttpClient`** | Axios base URL, timeouts, hub headers, auth callbacks. |
-| **`getFormErrors`**, **`getFieldErrors`** | Map Axios errors to form-level / field-level messages. |
-| **Types** | `LoginPayload`, `MutationOptions`, `ChangePasswordPayload`, … |
+| Export                                    | Purpose                                                                    |
+| ----------------------------------------- | -------------------------------------------------------------------------- |
+| **`api.auth`**                            | Login, MFA, security, SSO, users, session helpers (`api.auth.session.*`).  |
+| **`api.crm`**                             | Pipelines, objects, notes, emails, files, uploads, cache purge.            |
+| **`api.navigation`**                      | URL factories (`makeLink`, `updateLink`), route params, breadcrumbs.       |
+| **`store`**                               | `storage`, CRM nanostores (`table`, `user`, …), `tableUi` (pagination UI). |
+| **`hubContext`**                          | Hub / portal identifiers from browser storage.                             |
+| **`initializeHttpClient`**                | Axios base URL, timeouts, hub headers, auth callbacks.                     |
+| **`getFormErrors`**, **`getFieldErrors`** | Map Axios errors to form-level / field-level messages.                     |
+| **`resolveApiErrorDisplay`**              | Map API / transport errors to user-facing title, description, variant, retry/support (see below). |
 
-There is **no** `api.all()` or generic “invoke any route” helper — call the specific member on **`api`**.
+**4.0:** nested `api.*` only; `useTableUi()` + required `tableParams` on list mutations. See [CHANGELOG.md](./CHANGELOG.md).
+
+Naming rules and migration: [docs/PUBLIC-API-NAMING.md](./docs/PUBLIC-API-NAMING.md).
 
 ---
 
-## Mutation-style methods (`api.login`, …)
+## API error resolver (`resolveApiErrorDisplay`)
+
+WoodsPortal HTTP errors return `errorCode`, `category`, and `errorMessage` (see woodsportal-api `docs/API-ERROR-CODES.md`). **`resolveApiErrorDisplay(error, options?)`** turns any thrown value into stable UI copy:
 
-Most `api.*` factories wrap **`createMutation`**: invoke the factory **once** with optional **`MutationOptions`**, then call the returned **`mutate`** (often aliased, e.g. **`login`**) with a payload.
+```typescript
+import { resolveApiErrorDisplay } from 'woodsportal-client-sdk'
+
+const display = resolveApiErrorDisplay(err)
+// display.title, display.description, display.variant, display.showRetry, display.showSupport
+// display.errorCode, display.correlationId (when present)
+```
+
+**Behavior:**
+
+1. Non-HTTP failures (timeout, offline, 503) → transport variants via `classifyHttpError`.
+2. API responses → `parseApiErrorPayload` + lookup in `API_ERROR_DISPLAY_CONFIG` (all active codes + reserved fallbacks).
+3. Unknown `errorCode` → fallback by `category` (`AUTH`, `ACCESS`, `VALIDATION`, `FILE`, `RATE_LIMIT`, …).
+4. **Description:** prefers API `errorMessage` (server i18n); uses config `fallbackDescription` only when the API message is empty. Does **not** surface `detailedMessage` to end users.
+
+Auth-specific full-page copy (`HUBSPOT_REAUTH_REQUIRED`, `PORTAL_INACTIVE`, …) remains in **`getUnauthorizedPageCopy`**; the resolver delegates where appropriate.
+
+**When API adds a code:** update `ErrorCode.java`, `API-ERROR-CODES.md`, and `src/main/core/errors/api-error-display-config.ts` together. The sync guard test in `src/test/core/errors/` fails if an active code lacks config.
+
+---
+
+## Mutation-style methods (`api.auth.login`, …)
+
+Most nested factories wrap **`createMutation`**: invoke once with optional **`MutationOptions`**, then call the returned **`mutate`** or the **leaf alias** (e.g. **`login`**, **`list`**).
 
 **Loading:** **`isLoading()`** returns whether **any** in-flight call exists for that factory (overlapping calls are supported).
 
 **Errors:** **`onError`** runs when the request fails; the returned promise **still rejects** — use `try/catch` or `.catch()` in addition to `onError` when you need local control flow.
 
 ```typescript
-import type { LoginPayload } from "woodsportal-client-sdk";
-import { api } from "woodsportal-client-sdk";
-
-const { login, mutate, isLoading } = api.login({
-  onSuccess: async (data, payload) => {
-    // Persist session in app state if needed; tokens are handled inside the SDK login path
-  },
-  onError: (error, payload) => {
-    // Log a redacted message; map to UI state — avoid logging credentials
-  },
-  onLoadingChange: (loading) => {
-    // Drive a global or local spinner
-  },
-});
-
-await login({ username: "user@example.com", password: "…" });
+import type { LoginPayload } from 'woodsportal-client-sdk'
+import { api } from 'woodsportal-client-sdk'
+
+const { login, mutate, isLoading } = api.auth.login({
+    onSuccess: async (data, payload) => {
+        // Persist session in app state if needed; tokens are handled inside the SDK login path
+    },
+    onError: (error, payload) => {
+        // Log a redacted message; map to UI state — avoid logging credentials
+    },
+    onLoadingChange: (loading) => {
+        // Drive a global or local spinner
+    }
+})
+
+await login({ username: 'user@example.com', password: '…' })
 // `mutate` is identical to `login` here
 ```
 
@@ -114,23 +160,23 @@ await login({ username: "user@example.com", password: "…" });
 ## React example (login form)
 
 ```tsx
-import type { LoginPayload } from "woodsportal-client-sdk";
-import { api } from "woodsportal-client-sdk";
+import type { LoginPayload } from 'woodsportal-client-sdk'
+import { api } from 'woodsportal-client-sdk'
 
 const { login } = api.login({
-  onSuccess: () => undefined,
-  onError: () => undefined,
-  onLoadingChange: () => undefined,
-});
+    onSuccess: () => undefined,
+    onError: () => undefined,
+    onLoadingChange: () => undefined
+})
 
 export async function submitLogin(e: React.FormEvent<HTMLFormElement>) {
-  e.preventDefault();
-  const formData = new FormData(e.currentTarget);
-  const payload: LoginPayload = {
-    username: String(formData.get("username") ?? ""),
-    password: String(formData.get("password") ?? ""),
-  };
-  await login(payload);
+    e.preventDefault()
+    const formData = new FormData(e.currentTarget)
+    const payload: LoginPayload = {
+        username: String(formData.get('username') ?? ''),
+        password: String(formData.get('password') ?? '')
+    }
+    await login(payload)
 }
 ```
 
@@ -178,8 +224,8 @@ npm link woodsportal-client-sdk
 Consume with the same import paths as npm:
 
 ```ts
-import { api } from "woodsportal-client-sdk";
-import { useTable, useSync } from "woodsportal-client-sdk/react";
+import { api } from 'woodsportal-client-sdk'
+import { useTable, useSync } from 'woodsportal-client-sdk/react'
 // import { useTable, useSync } from "woodsportal-client-sdk/vue";
 // import { useTable, useSync } from "woodsportal-client-sdk/angular";
 ```
@@ -189,11 +235,11 @@ After `npm run build`, the main entry and framework adapters (`/react`, `/vue`,
 ### React
 
 ```tsx
-import { useTable } from "woodsportal-client-sdk/react";
+import { useTable } from 'woodsportal-client-sdk/react'
 
 function ObjectsTable() {
-  const table = useTable();
-  // table.tableData, table.setTableData(...)
+    const table = useTable()
+    // table.tableData, table.setTableData(...)
 }
 ```
 
@@ -203,9 +249,9 @@ Call composables inside `setup()` (or `<script setup>`):
 
 ```vue
 <script setup lang="ts">
-import { useTable } from "woodsportal-client-sdk/vue";
+import { useTable } from 'woodsportal-client-sdk/vue'
 
-const table = useTable();
+const table = useTable()
 </script>
 ```
 
@@ -214,17 +260,93 @@ const table = useTable();
 Call composables in an injection context (constructor, field initializer, or `runInInjectionContext`):
 
 ```typescript
-import { Component } from "@angular/core";
-import { useTable } from "woodsportal-client-sdk/angular";
+import { Component } from '@angular/core'
+import { useTable } from 'woodsportal-client-sdk/angular'
 
-@Component({ /* ... */ })
+@Component({
+    /* ... */
+})
 export class ObjectsTableComponent {
-  readonly table = useTable();
+    readonly table = useTable()
 }
 ```
 
 ---
 
+## Cache purge (CRM Sync)
+
+Prefer **`POST /api/{hubId}/{portalId}/cache-purge-jobs`** over habitual `cache=false` on list reads. Requires `FEATURE_CACHE_PURGE_API_ENABLED` on the API.
+
+| Export                                                  | Use                                                 |
+| ------------------------------------------------------- | --------------------------------------------------- |
+| `createCachePurgeJob`                                   | POST + optional warm job poll                       |
+| `buildCrmListPurgeTarget` / `buildCrmSinglePurgeTarget` | List or detail scope                                |
+| `buildEngagementPurgeTarget`                            | `notes` / `emails` / `files` (requires `recordIds`) |
+| `purgeCrmListCache` / `purgeEngagementCaches`           | Convenience wrappers returning `PurgeResult`        |
+| `purgeCrmObjectDataCache`                               | Legacy list-only boolean shorthand                  |
+
+API guide: `woodsportal-api/docs/CACHE-PURGE-API.md` in the monorepo. Types: `src/types/cache-purge.ts`; helpers: `src/utils/cache/`.
+
+---
+
+## MFA & login (client lane)
+
+When `POST /api/auth/login` returns `twoFactorRequired: true`, the SDK stores **only** the temporary access JWT — **not** the refresh token. Complete MFA with `api.verifyOtp()` (or pending passkey verify); on success the SDK persists the full session.
+
+**Full guide:** [`docs/MFA-SECURITY-SDK.md`](docs/MFA-SECURITY-SDK.md) (every method, payload, and example).
+
+Backend reference: `woodsportal-api/docs/MFA-FRONTEND-DEVELOPER-GUIDE.md`.
+
+### Login & MFA step (unauthenticated)
+
+| SDK method                                                            | HTTP                                                            | Purpose                                                    |
+| --------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------- |
+| `login({ username, password })`                                       | `POST /api/auth/login?hubId=`                                   | Password login; may return `twoFactorRequired`             |
+| `verifyOtp({ token, otp, method })`                                   | `POST /api/auth/verify-otp?hubId=`                              | Complete OTP/TOTP/backup MFA step; full session on success |
+| `sendMfaOtp({ token, method })`                                       | `POST /api/auth/mfa/pending/otp/send`                           | Resend OTP or switch to email/SMS on MFA gate              |
+| `pendingPasskeyOptions({ token, portalId? })`                         | `POST /api/auth/mfa/pending/passkey/authenticate/options`       | Start passkey MFA-step ceremony                            |
+| `pendingPasskeyVerify({ token, challengeId, credential, portalId? })` | `POST /api/auth/mfa/pending/passkey/authenticate/verify?hubId=` | Finish passkey MFA step; full session on success           |
+| `passkeyLoginOptions({ email, hubId?, portalId? })`                   | `POST /api/auth/passkey/login/options?hubId=`                   | Passwordless passkey login start                           |
+| `passkeyLoginVerify({ challengeId, credential, portalId? })`          | `POST /api/auth/passkey/login/verify?hubId=`                    | Passwordless login finish; may still require MFA           |
+
+### MFA enrollment (authenticated)
+
+| SDK method                                                                  | HTTP                                                         | Purpose                                  |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------- |
+| `getMfaStatus({ portalId? })`                                               | `GET /api/auth/mfa/status?portalId=`                         | Enrollment + policy snapshot             |
+| `setMfaPreferences({ defaultMethod, portalId? })`                           | `PUT /api/auth/mfa/preferences?portalId=`                    | Set scoped default MFA method            |
+| `startPhoneVerify({ phone })`                                               | `POST /api/auth/mfa/phone/verify/start`                      | Send phone verification OTP (E.164)      |
+| `confirmPhoneVerify({ phone, code })`                                       | `POST /api/auth/mfa/phone/verify/confirm`                    | Confirm phone; enables SMS at login      |
+| `totpEnrollStart({ portalId? })`                                            | `POST /api/auth/mfa/totp/enroll/start?portalId=`             | Start TOTP; returns QR/`otpauthUri`      |
+| `totpEnrollVerify({ code, portalId? })`                                     | `POST /api/auth/mfa/totp/enroll/verify?portalId=`            | Confirm TOTP; backup codes returned once |
+| `totpDisable({ password })`                                                 | `POST /api/auth/mfa/totp/disable`                            | Disable TOTP for current scope           |
+| `webauthnRegisterOptions({ portalId? })`                                    | `POST /api/auth/mfa/webauthn/register/options?portalId=`     | Passkey registration ceremony            |
+| `webauthnRegisterVerify({ challengeId, credential, nickname?, portalId? })` | `POST /api/auth/mfa/webauthn/register/verify?portalId=`      | Complete passkey registration            |
+| `webauthnAuthOptions({ portalId? })`                                        | `POST /api/auth/mfa/webauthn/authenticate/options?portalId=` | Logged-in passkey re-verify              |
+| `webauthnAuthVerify({ challengeId, credential, portalId? })`                | `POST /api/auth/mfa/webauthn/authenticate/verify?portalId=`  | Complete logged-in passkey verify        |
+| `listWebauthnCredentials({ portalId? })`                                    | `GET /api/auth/mfa/webauthn/credentials?portalId=`           | List passkeys                            |
+| `deleteWebauthnCredential({ credentialRecordId, portalId? })`               | `DELETE /api/auth/mfa/webauthn/credentials/{id}?portalId=`   | Remove a passkey                         |
+
+WebAuthn ceremonies use `@simplewebauthn/browser` in the host app; the SDK transports credential JSON only.
+
+---
+
+## Security settings (client lane)
+
+Use dedicated security endpoints for the account Security page — **not** `GET /me` + `GET /mfa/status`. Full contract: `woodsportal-api/docs/SECURITY-FRONTEND-DEVELOPER-GUIDE.md`. **Examples:** [`docs/MFA-SECURITY-SDK.md`](docs/MFA-SECURITY-SDK.md).
+
+| SDK method                                                 | HTTP                                                 | Purpose                                       |
+| ---------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------- |
+| `getSecurityOverview({ portalId? })`                       | `GET /api/auth/security/overview?portalId=`          | Password age, MFA methods, policy flags       |
+| `getSecurityLoginActivity({ page?, limit?, sort? })`       | `GET /api/auth/security/login-activity`              | Paginated login history                       |
+| `getSecuritySessions({ currentFamilyId?, refreshToken? })` | `GET /api/auth/security/sessions`                    | Active sessions; pass refresh to mark current |
+| `revokeSecuritySession({ familyId, refreshToken? })`       | `POST /api/auth/security/sessions/{familyId}/revoke` | Sign out one device                           |
+| `revokeOtherSecuritySessions({ refreshToken? })`           | `POST /api/auth/security/sessions/revoke-others`     | Sign out all other devices                    |
+
+Pass `refreshToken` (or use `getRefreshToken()` from SDK cookies) so the API can mark the current session when listing or revoking others.
+
+---
+
 ## Security & privacy
 
 - Send credentials and tokens **only over HTTPS** in production.

package/dist/adapters/angular/index.d.ts

@@ -1,28 +1,93 @@
-import { E as EmailState, M as MultiObjectTableState, N as NoteState, S as SyncState, T as TableState, U as UploaderState } from '../../use-uploader-dlc_3esL.js';
+import { F as FileState, M as MultiObjectTableState, U as UploaderState } from '../../use-file-BcO5l-Zf.js';
+import { E as EmailState, N as NoteState, O as ObjectState, S as SyncState, T as TableState, a as TableUiState, U as UserState } from '../../use-sync-BQfzHacf.js';
 
 declare const useTable: () => TableState & {
-    setObjectsData(response: any): Promise<void>;
+    setObjectsQueryParams(params: any): void;
+    setMultiObjectsQueryParams(hubspotObjectTypeId: string, params: any): void;
+    setObjectsData(response: any, context?: {
+        stageId?: string | number;
+    }): Promise<void>;
     setTableData(response: any, payload: any): void;
     modifiedObjectsData(results: any): void;
     clearTablePrependData(): void;
+    clearLatestTablePrependData(): void;
     setTablePrependData(response: any, props?: any): Promise<void>;
+    updateTablePrependData(response: any, payload?: any): any;
+};
+declare const useTableUi: () => TableUiState & {
+    setTableUniqueId(v: string | null): void;
+    setSort(v: string): void;
+    setLimit(v: number): void;
+    setAfter(v: string): void;
+    setPage(v: number | string): void;
+    setNextPage(v: number | string): void;
+    setStageId(v: number | string): void;
+    setSelectedStage(v: string): void;
+    setTotalItems(v: number): void;
+    setNumOfPages(v: number): void;
+    setCurrentPage(v: number): void;
+    setSearch(v: string): void;
+    setFilterPropertyName(v: string): void;
+    setFilterOperator(v: string): void;
+    setFilterValue(v: string): void;
+    setIsPrimaryCompany(v: boolean | null): void;
+    setTableFilterData(v: Record<string, unknown>): void;
+    setTableDefPermissions(v: Record<string, unknown>): void;
+    setView(mView: string | null): void;
+    changePipeline(mView: string | null): void;
+    setSelectedPipeline(pipelines: any[], pipeLineId?: string): void;
+    resetTableParam(): void;
+    getTableParam(companyAsMediator?: boolean, currentPageOverride?: number): {
+        after: string | number;
+    } | {
+        after?: string | undefined;
+        limit: number;
+        page: string | number;
+    };
+    buildListTableParams(options?: {
+        companyAsMediator?: boolean;
+        currentPageOverride?: number;
+    }): {
+        after: string | number;
+    } | {
+        after?: string | undefined;
+        limit: number;
+        page: string | number;
+    };
+    setGridData(type: string, deals: any[]): Promise<any[]>;
+    setDefaultPipeline(data: any, hubspotObjectTypeId: string, viewName?: string): any;
 };
 declare const useMultiObjectActions: () => MultiObjectTableState & {
     setMultiObjectData(response: any, payload: any): void;
     clearMultiObjectPrependData(hubspotObjectTypeId?: string): void;
+    clearLatestMultiObjectPrependData(hubspotObjectTypeId?: string): void;
     setMultiObjectPrependData(response: any, props?: any): Promise<void>;
 };
+declare const useObject: () => ObjectState & {
+    setObjectData(response: any, payload?: any): void;
+    updateObjectData(response: any, payload?: any): any;
+    setObjectAssociationPrependData(response: any, props?: any): Promise<void>;
+    clearLatestObjectAssociationPrependData(props?: any): void;
+    clearObjectData(): void;
+};
 declare const useNote: () => NoteState & {
+    setListQueryParams(params: any): void;
     setNotes(response: any, payload: any): void;
     setPrependNote(response: any): Promise<void>;
+    clearLatestPrependNote(): void;
     clearPrependNotes(): void;
-    updatePrependNote(response: any): Promise<void>;
+    updatePrependNote(response: any): Promise<any>;
 };
 declare const useEmail: () => EmailState & {
+    setListQueryParams(params: any): void;
     setEmails(response: any, payload: any): void;
     setPrependEmail(response: any): Promise<void>;
+    clearLatestPrependEmail(): void;
     clearPrependEmails(): void;
-    updatePrependEmail(response: any): Promise<void>;
+    updatePrependEmail(response: any): Promise<any>;
+};
+declare const useUser: () => UserState & {
+    setProfile(response: any): void;
 };
 declare const useSync: () => SyncState & {
     setIsSyncLoading(status: boolean): void;
@@ -34,5 +99,12 @@ declare const useUploader: () => UploaderState & {
     setAttachment(response: any): void;
     clearAttachments(): void;
 };
+declare const useFile: () => FileState & {
+    setListQueryParams(params: any): void;
+    setFiles(response: any, payload: any): void;
+    updateTreeWithCreate(parentFolderId: string, response: "loading" | any, _createKind?: "file" | "folder"): Promise<void>;
+    clearLatestTreeLoadingNode(parentFolderId: string): void;
+    clearFiles(): void;
+};
 
-export { useEmail, useMultiObjectActions, useNote, useSync, useTable, useUploader };
+export { useEmail, useFile, useMultiObjectActions, useNote, useObject, useSync, useTable, useTableUi, useUploader, useUser };

package/dist/adapters/angular/index.js

@@ -1,7 +1,12 @@
-import { bindStoreWithActions } from '../../chunk-Y5MRAAGK.js';
-import { createAdapterHooks } from '../../chunk-OSSWRJXO.js';
-import '../../chunk-6OS7H3VO.js';
-import '../../chunk-NB7AINV4.js';
+import { bindStoreWithActions } from '../../chunk-AYTO6ND7.js';
+import { createAdapterHooks } from '../../chunk-OH7VT6MX.js';
+import '../../chunk-2OLIVT2F.js';
+import '../../chunk-JSXP2F2H.js';
+import '../../chunk-XDYXEYDM.js';
+import '../../chunk-32ERSTFY.js';
+import '../../chunk-DB6W3CJT.js';
+import '../../chunk-KGNMN7B3.js';
+import '../../chunk-COHBSTHF.js';
 import { inject, DestroyRef, signal } from '@angular/core';
 
 function createAngularStoreComposable(store, actions) {
@@ -26,9 +31,9 @@ function createAngularStoreComposable(store, actions) {
   };
 }
 
-// src/adapters/angular/index.ts
-var { useTable, useMultiObjectActions, useNote, useEmail, useSync, useUploader } = createAdapterHooks(createAngularStoreComposable);
+// src/main/adapters/angular/index.ts
+var { useTable, useTableUi, useMultiObjectActions, useObject, useNote, useEmail, useUser, useSync, useUploader, useFile } = createAdapterHooks(createAngularStoreComposable);
 
-export { useEmail, useMultiObjectActions, useNote, useSync, useTable, useUploader };
+export { useEmail, useFile, useMultiObjectActions, useNote, useObject, useSync, useTable, useTableUi, useUploader, useUser };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map