@eaera-com/cms-sdk 0.1.65 → 0.1.67

package/README.md

@@ -1,479 +0,0 @@
-# @eaera-com/cms-sdk
-
-Data-access layer for EAERA CMS, built for **Nuxt 3** consumers.
-
-- **HTTP**: [`ofetch`](https://github.com/unjs/ofetch) (same engine as Nuxt `$fetch`) — retry, timeout, typed responses, casing opt-in.
-- **State**: [Pinia](https://pinia.vuejs.org/) + a **built-in cookie-based persistence plugin** (per-state, optional `httpOnly`) — no `pinia-plugin-persistedstate` dependency.
-- **Auth**: single-source-of-truth `TokenManager` with pluggable storage adapters (memory / localStorage / cookie / httpOnly-bridge).
-- **Multi-backend**: one `createCmsSDK()` facade can target multiple endpoints (CMS, report, …) sharing one token + hooks.
-- **Domains**: `auth` · `content` · `rules` · `executions` · `settings` — five typed services + five Pinia stores.
-- **Explicit imports**: nothing is auto-imported. You import exactly what you use.
-
-> The auth service mirrors the **confirmed** CMS backend surface (login / logout / OAuth refresh only). The content/rules/executions/settings domains ship with a **mock mode** so the SDK is usable before the backend is fully wired; flip `mock: false` once the endpoints exist.
-
-## Requirements
-
-| Dep | Version |
-|---|---|
-| Node | `>= 20` (dev repo pins `22` via `.nvmrc`) |
-| Nuxt | `^3.0.0 \|\| ^4.0.0` (if using the Nuxt module) |
-| Vue | `^3.5.0` (peer) |
-| Pinia | `^3.0.4` (peer) |
-
-## Install
-
-```bash
-pnpm add @eaera-com/cms-sdk
-# Peer deps (usually already present in a Nuxt app):
-#   pnpm add pinia vue
-```
-
-> Persistence is **built into the SDK module** (cookie-based, per-state, optional `httpOnly`). No extra package or module is required.
-
-## Quick start (Nuxt 3)
-
-Register the module and point it at your runtime config:
-
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  modules: [
-    '@pinia/nuxt',
-    '@eaera-com/cms-sdk/nuxt',
-  ],
-  runtimeConfig: {
-    public: {
-      cmsUrl: process.env.CMS_URL ?? 'https://cms.example.com',
-      reportUrl: process.env.REPORT_URL,
-      clientId: process.env.CMS_CLIENT_ID ?? 'web',
-    },
-  },
-  cmsSdk: {
-    // Each value is a KEY NAME in runtimeConfig.public (not the URL itself).
-    endpoints: { cms: 'cmsUrl', report: 'reportUrl' },
-    clientId: 'clientId',          // runtimeConfig.public key holding the client id
-    mock: process.env.NODE_ENV !== 'production',
-  },
-})
-```
-
-> The module forces `'memory'` storage for `TokenManager` internally — the httpOnly cookie `cms_access_token` (managed by the module's `/api/cms/*` routes) is the real token persistence. The `storage` option only matters for standalone `createCmsSDK()`.
-
-The module exposes `useNuxtApp().$cms`. Stores are **imported explicitly**:
-
-```vue
-<script setup lang="ts">
-import { useContentStore, CONTENT_TYPE } from '@eaera-com/cms-sdk'
-
-const { $cms } = useNuxtApp()
-const content = useContentStore()   // Pinia store; SDK attached by the module
-
-await content.fetchByType(CONTENT_TYPE.MT5_ACCOUNT, { perPage: 50 })
-</script>
-
-<template>
-  <div v-for="acc in content.mt5Accounts" :key="acc.uuid">
-    {{ acc.data.login }} — {{ acc.data.group }} (leverage 1:{{ acc.data.leverage }})
-  </div>
-</template>
-```
-
-## Imperative usage (no Nuxt module)
-
-```ts
-import { createPinia } from 'pinia'
-import { createCmsSDK } from '@eaera-com/cms-sdk'
-
-const sdk = createCmsSDK({
-  endpoints: { cms: 'https://cms.example.com' },
-  clientId: 'web',
-  credentials: { storage: 'localStorage' },
-  mock: true,
-})
-
-const accounts = await sdk.content.list<Mt5Account>({ type: 'Mt5Account', perPage: 50 })
-const rule     = await sdk.rules.detail('abc-uuid')
-```
-
-To use the Pinia stores outside Nuxt, install Pinia + the built-in persistence plugin and attach the SDK. (Pinia 3.x defers `pinia.use` plugins until the pinia is installed on an app, so `app.use(pinia)` is required. httpOnly state is **not** available standalone — use a non-httpOnly storage such as `localStorage`.)
-
-```ts
-import { createApp } from 'vue'
-import { createPinia } from 'pinia'
-import { createPersistPlugin, useContentStore } from '@eaera-com/cms-sdk'
-
-const pinia = createPinia()
-createApp({}).use(pinia)
-pinia.use(createPersistPlugin({ storage: localStorage, ssr: false }))
-
-const content = useContentStore(pinia)
-content.setSdk(sdk)
-await content.fetchByType('Mt5Account')
-```
-
----
-
-## API reference
-
-### `createCmsSDK(options)` → `ICmsSDK`
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `endpoints` | `{ cms: string; report?: string; poolTrading?: string; [k]: string }` | — | **Required.** Backend URLs; each becomes a `$Fetch` in `sdk.apis`. |
-| `clientId` | `string` | — | Sent as `X-Client-Id` header. |
-| `credentials` | `ICredentialsConfig` | `{ storage: 'cookie' }` | Token storage + header config (see below). |
-| `device` | `{ deviceId?, deviceIp? }` | — | Static or function values sent as `DeviceID` / `DeviceIP`. |
-| `timeout` | `number` | `30000` | Request timeout (ms). |
-| `retry` | `number` | `2` | Retries on `408/425/429/5xx`. |
-| `mock` | `boolean` | `false` | Return fake data instead of hitting the backend. |
-| `responseCasing` | `'camel' \| 'snake'` | `'camel'` | Asks the backend for a casing via `x-response-casing`. |
-| `requestCasing` | `'camel' \| 'snake'` | `'camel'` | Declares request-body casing via `x-request-casing`. |
-| `onError` | `(e: CmsError) => void` | — | Global error callback (after normalisation). |
-| `onUnauthorized` | `(e: CmsError) => void` | — | Called on `401` (e.g. force logout). |
-| `onToken` | `(token: string \| null) => void \| Promise<void>` | — | Hook fired whenever the access token changes (refresh, 401). |
-| `refresh` | `() => Promise<string \| null>` | — | Silent refresh on 401 (Nuxt module wires this to `/api/cms/refresh`). |
-| `authRoute` | `$Fetch` | — | `$Fetch` used for token-lifecycle flows so the httpOnly cookie is set atomically. |
-
-**Returns** `ICmsSDK`:
-
-| Member | Type | Description |
-|---|---|---|
-| `apis` | `Record<string, $Fetch>` | One typed fetcher per endpoint (e.g. `sdk.apis.cms`, `sdk.apis.report`). |
-| `tokenManager` | `TokenManager` | Single source of truth for the access token. |
-| `auth` | `IAuthService` | Auth domain service (login / logout / token). |
-| `content` | `IContentService` | Content CRUD + actions. |
-| `rules` | `IRulesService` | Content-rule CRUD. |
-| `executions` | `IExecutionsService` | Read-only execution feed. |
-| `settings` | `ISettingsService` | Dashboard settings (monitored groups). |
-| `addRequestMiddleware(target, mw)` | `() => void` | Register a runtime request hook (`'all'` or an endpoint name); returns an unsubscribe. |
-| `setMock(enabled)` | `(b) => void` | Toggle mock mode at runtime. |
-| `syncToken(token)` | `(t: string \| null) => Promise<void>` | Set/clear token (login/restore/logout). |
-
-### `sdk.auth` — Auth service
-
-| Method | Params | Returns | Notes |
-|---|---|---|---|
-| `login` | `payload: ILoginPayload, userAgent?` | `IAuthRouteResponse` | `POST /api/auth/login` (or `/api/cms/login` via proxy). |
-| `logout` | — | `unknown` | `POST /api/auth/logout`. |
-| `token` | — | `ITokenResponse` | OAuth refresh (`POST /api/oauth/token`); returns the new access token in the body. |
-
-> When a `routeApi` (Nuxt module) is configured, all three flows route through the `/api/cms/*` proxies so httpOnly cookies are set / cleared / rotated atomically.
-
-### `sdk.content` — Content service
-
-Generic CMS content CRUD over the **singular** `/api/v1/content` namespace; type-specific reads use `query: { type }`.
-
-| Method | Params | Returns | Notes |
-|---|---|---|---|
-| `list` | `query?: ContentQuery` | `ContentListResponse<ContentItem<T>>` | Paginated (1-based `page`/`perPage`), filterable by `type`/`status`/`packId`. |
-| `detail` | `uuid: string` | `ContentItem<T>` | Throws on miss. |
-| `create` | `payload: ContentCreatePayload<T>` | `ContentItem<T>` | POST. |
-| `update` | `uuid, payload: ContentUpdatePayload<T>` | `ContentItem<T>` | PUT (data/slug). |
-| `remove` | `uuid: string` | `void` | Soft-delete. |
-| `listActions` | `uuid: string` | `ContentAction[]` | CT actions available on the item. |
-| `invokeAction` | `uuid, actionName, payload?` | `ActionResponse` | Run a CT action (e.g. `change_group`, `change_leverage`). |
-
-```ts
-const { items } = await sdk.content.list<Mt5Account>({ type: 'Mt5Account', perPage: 50 })
-
-await sdk.content.invokeAction(acc.uuid, 'change_leverage', {
-  params: { newLeverage: 100 },
-  intentionId: crypto.randomUUID(),
-})
-```
-
-### `sdk.rules` — Rules service
-
-Content-rule CRUD over `/api/v1/rules`. A rule binds a **trigger** → **condition** → **execution**.
-
-| Method | Params | Returns | Notes |
-|---|---|---|---|
-| `list` | `query?: RuleListQuery` | `ContentRuleListResponse` | No pagination (`total === items.length`). |
-| `detail` | `uuid: string` | `ContentRule` | Full rule. |
-| `create` | `payload: RuleCreatePayload` | `ContentRule` | POST (flat payload). |
-| `update` | `uuid, payload: RuleUpdatePayload` | `ContentRule` | PUT. |
-| `remove` | `uuid: string` | `void` | Deactivate. |
-
-The SDK ships **rule-builder helpers** so the dashboard authors valid triggers + actions (see `services/rules/triggers.ts` + `conditions.ts`):
-
-```ts
-import {
-  buildSignalTrigger, buildCronTrigger, CRON_PRESETS,
-  CONDITION_FIELDS, CONDITION_OPERATORS,
-  ACTION_KINDS, LEVERAGE_OPTIONS,
-} from '@eaera-com/cms-sdk'
-
-await sdk.rules.create({
-  name: 'High drawdown → move group',
-  contentType: 'Mt5Account',
-  trigger: buildSignalTrigger(),                       // signal over the metric stream
-  conditionType: 'expression',
-  conditionExpr: 'account_metric_by_deal.relative_balance_drawdown > 0.30',
-  executionType: 'action',
-  executionParams: { actionName: 'change_group', params: { newGroup: 'live\\restricted' } },
-})
-```
-
-### `sdk.executions` — Executions service (read-only)
-
-Backs the detection feed + the action-history table. No remediation write endpoint — operator remediation goes through `content.invokeAction`.
-
-| Method | Params | Returns | Notes |
-|---|---|---|---|
-| `list` | `params?: ExecutionListParams` | `ExecutionListResponse` | `GET /api/v1/executions`, or `GET /api/v1/rules/content/{contentId}/executions` when `contentId` is set. |
-| `detail` | `uuid: string` | `ContentExecution` | Single execution row. |
-
-### `sdk.settings` — Settings service
-
-| Method | Params | Returns | Notes |
-|---|---|---|---|
-| `getMonitoredGroups` | — | `Promise<string[]>` | Reads `setting.dashboard.monitored_groups`. |
-| `setMonitoredGroups` | `groups: string[]` | `Promise<string[]>` | Writes the setting. |
-
-### Types
-
-Each domain exports its DTOs (`ContentItem<T>`, `Mt5Account`, `ContentRule`, `ContentExecution`, …) plus the helper types (`ConditionField`, `ActionKindDef`, `CronPreset`, `TriggerMode`, `LeverageOption`, …). The mt5 pack registers **9 content types** via `CONTENT_TYPE` (`Mt5Server`, `Mt5Account`, `Mt5SyncState`, `ReportDefinition`, `LlmPrompt`, `LlmConversation`, `KalshiServer`, `KalshiEvent`, `KalshiFuture`). See `types-and-constants.md` in the docs hub for the full catalog.
-
-### Helpers
-
-```ts
-import { formatPrice, computeSpread, categoryLabel } from '@eaera-com/cms-sdk'
-
-formatPrice(1.0876, 5)        // '1.08760'
-computeSpread(1.0875, 1.0876) // 0.0001
-categoryLabel('fx')           // 'Forex'
-```
-
----
-
-## Pinia stores
-
-All stores must be **imported explicitly**. The Nuxt module attaches the SDK automatically; elsewhere call `setSdk(sdk)` once.
-
-### `useAuthStore` — `cms-auth`
-
-| | |
-|---|---|
-| **State** | `authUser`, `employee`, `allowRoutes`, `accessToken` (reactive mirror of the token) |
-| **Getters** | `isLoggedIn` → `!!accessToken`; `routeList` → parsed route permissions |
-| **Actions** | `setSdk(sdk)`, `login`, `refreshToken`, `logout` |
-| **Persist** | `fields: { authUser: { httpOnly: true } }` → cookie `cms-persist-auth.authUser` (httpOnly, server-written via `/api/cms-sdk/persist`) |
-
-> `accessToken` is a **reactive mirror** of `TokenManager.currentToken`; it is intentionally **NOT** persisted by Pinia. The durable copy lives in the httpOnly cookie (managed by the Nuxt module), and the mirror is restored from that cookie on SSR.
-
-> `allowRoutes` is **derived** from `authUser.allowRoutes` via a watcher, so the menu stays in sync with the persisted user profile on hydrate.
-
-### `useContentStore` — `cms-content`
-
-Holds **9 typed slices** (one per mt5-pack CT) and exposes **7 generic actions** that delegate 1:1 to the `content` service.
-
-| | |
-|---|---|
-| **State** | `mt5Servers`, `mt5Accounts`, `mt5SyncStates`, `reportDefinitions`, `llmPrompts`, `llmConversations`, `kalshiServers`, `kalshiEvents`, `kalshiFutures`, `isLoading`, `loadError`, `lastQueryByType` |
-| **Getters** | `isEmpty`, `groups` (distinct `Mt5Server.data.name`), `getByType(typeName)`, `getActionsForType(typeName)`, `knownTypes` |
-| **Actions** | `setSdk`, `fetchByType(typeName, query?)`, `fetchOne(uuid)`, `create`, `update`, `remove`, `fetchActions(uuid)`, `invokeAction(uuid, actionName, payload?)` |
-| **Persist** | `pick: ['lastQueryByType']` → cookie `cms-content-v1.lastQueryByType` (non-httpOnly) |
-
-> Mutations (`create`/`update`/`remove`/`invokeAction`) do **not** auto-refetch the affected slice — call `fetchByType(typeName)` again if you need it refreshed.
-
-### `useRulesStore` — `cms-rules`
-
-| | |
-|---|---|
-| **State** | `items`, `total`, `isLoading`, `loadError`, `lastQuery`, `selectedRule` |
-| **Getters** | `isEmpty`, `activeRules` |
-| **Actions** | `setSdk`, `fetch(query?)`, `select(uuid)`, `create`, `update`, `toggle(uuid, active)`, `remove` |
-| **Persist** | `pick: ['lastQuery']` → cookie `cms-rules-v1.lastQuery` (non-httpOnly) |
-
-### `useExecutionsStore` — `cms-executions`
-
-| | |
-|---|---|
-| **State** | `items`, `total`, `isLoading`, `loadError`, `lastParams` |
-| **Getters** | `isEmpty` |
-| **Actions** | `setSdk`, `list(params?)` (read-only) |
-| **Persist** | `pick: ['lastParams']` → cookie `cms-executions-v1.lastParams` (non-httpOnly) |
-
-### `useSettingsStore` — `cms-settings`
-
-| | |
-|---|---|
-| **State** | `monitoredGroups`, `isLoading`, `loadError` |
-| **Getters** | `isEmpty` |
-| **Actions** | `setSdk`, `fetchGroups()`, `addGroup(group)`, `removeGroup(group)` (optimistic + rollback) |
-| **Persist** | `pick: ['monitoredGroups']` → cookie `cms-settings-v1.monitoredGroups` (non-httpOnly) |
-
----
-
-## Authentication & token flow
-
-> **Primary call path: Pinia store actions.** Call `useAuthStore()` actions from your app — they own the SDK and the reactive state. `$cms.*` (services / raw `$Fetch`) is an escape hatch.
-
-The durable token copy lives in an **httpOnly cookie** (`cms_access_token`) managed by the Nuxt module; a parallel `cms_refresh_token` cookie backs silent refresh. `TokenManager` is the in-memory source for request headers; `useAuthStore.accessToken` is a reactive mirror (restored from the cookie on SSR, **never** persisted to localStorage).
-
-### How it flows (Nuxt module)
-
-```
-login    → useAuthStore.login() → /api/cms/login (server route)
-            → backend POST /api/auth/login → token in response BODY (accessToken)
-            → route sets httpOnly cookies cms_access_token + cms_refresh_token (atomic)
-            → returns { ..., token } → client mirrors token in memory
-logout   → useAuthStore.logout() → /api/cms/logout
-            → backend POST /api/auth/logout (Bearer from cookie) + both cookies cleared
-refresh  → on 401, createApi calls /api/cms/refresh once
-            → backend /api/oauth/token (grant_type=refresh_token, reads cms_refresh_token cookie)
-            → rotates both cookies, replays the request; on failure clears session + onUnauthorized
-sliding  → rotated token in response header → onToken → /api/cms/set-token (cookie refreshed, no drift)
-data     → useContentStore.fetchByType() / useRulesStore.fetch() → direct client→backend
-            → onRequest injects Authorization from TokenManager
-F5       → SSR reads httpOnly token cookie → restores TokenManager + accessToken mirror;
-            persist plugin hydrates authUser (cms-persist-auth.authUser) from its cookie
-401      → onResponseError → onToken(null) → /api/cms/clear-token + onUnauthorized fired
-```
-
-### Server routes registered by the module
-
-| Route | Purpose |
-|---|---|
-| `POST /api/cms/login` | login → backend `/api/auth/login`, sets httpOnly `cms_access_token` + `cms_refresh_token` from body, returns `{ ..., token }` |
-| `POST /api/cms/logout` | logout (backend `POST /api/auth/logout` + clears both cookies) |
-| `POST /api/cms/refresh` | silent refresh — reads httpOnly `cms_refresh_token` → backend `/api/oauth/token` (`grant_type=refresh_token`), rotates both cookies, returns new access token |
-| `POST /api/cms/set-token` | sync cookie on sliding-refresh / external token restore |
-| `DELETE /api/cms/clear-token` | clear cookie on 401 |
-| `POST /api/cms-sdk/persist` | set/clear an **allowlisted** httpOnly persist cookie (internal persistence plugin) |
-
-These are thin proxies (raw `ofetch`, no SDK instance) — they read `device_id`/`device_ip`/`user-agent` from the request, call the backend, and set/clear the httpOnly cookie.
-
-### `TokenManager`
-
-```ts
-sdk.tokenManager.get()       // string | null
-sdk.tokenManager.has()       // boolean
-sdk.tokenManager.set(t)      // store + onRefreshed hook
-sdk.tokenManager.clear()
-sdk.tokenManager.getHeader() // `${prefix}${token}` ready for a header
-sdk.tokenManager.swapStorage(storage) // upgrade storage at runtime
-```
-
-### `sdk.syncToken(token)`
-
-Used by login (via the route body `token`) / external SSO / 401. When an `onToken` hook is configured (the Nuxt module wires one), `syncToken` awaits it (sets memory + syncs the httpOnly cookie); otherwise it falls back to `TokenManager.set/clear`.
-
-```ts
-await sdk.syncToken('jwt-from-external-sso') // set
-await sdk.syncToken(null)                    // clear
-```
-
-### Credentials storage (TokenManager backend)
-
-The Nuxt module forces **`'memory'`** for TokenManager (the httpOnly cookie is the real persistence). For standalone `createCmsSDK()` you can choose:
-
-| `storage` | Backend | Use when |
-|---|---|---|
-| `'memory'` | in-process variable | SSR-safe; token lost on reload |
-| `'localStorage'` | browser localStorage | SPA, acceptable XSS exposure |
-| `'cookie'` | browser cookie (`document.cookie`) | SPA only — **client-side**; absent during SSR |
-
-### Requirements (Nuxt)
-
-- The SDK registers its **built-in cookie-based persistence plugin** automatically via the Nuxt module — **no `pinia-plugin-persistedstate` (or any extra module) is needed**. Persistence is per-state: sensitive state (`authUser`) uses an **httpOnly cookie** written through `/api/cms-sdk/persist`, while UI prefs (`lastQueryByType`, `lastQuery`, `lastParams`, `monitoredGroups`) use **non-httpOnly cookies** written directly on the client. Both are SSR-readable (instant on F5).
-- The httpOnly cookie is **not readable by JS**; client-side calls rely on the store mirror restored from the SSR payload.
-
-> Cookie defaults for the httpOnly cookie: `Secure`, `SameSite=Lax`, `Path=/`, `Max-Age=30 days`, `httpOnly: true` (see `COOKIE_DEFAULTS`).
-
-> **Cookie size limit:** cookies are ~4 KB. If your JWT exceeds this, the set-token/login route will fail; consider smaller tokens.
-
----
-
-## Error handling
-
-Every failed request is normalised to a `CmsError` and passed to `onError` (and `onUnauthorized` on 401). You may also `try/catch` locally.
-
-```ts
-import { CmsError } from '@eaera-com/cms-sdk'
-
-try {
-  await sdk.content.detail('missing-uuid')
-} catch (e) {
-  const err = e as CmsError
-  err.message          // string
-  err.statusCode       // number (0 = network)
-  err.code             // string
-  err.fieldErrors      // Record<string,string> | undefined (422)
-  err.requestId        // from x-request-id header
-  err.isUnauthorized   // 401
-  err.isValidation     // 422
-  err.isNetwork        // statusCode === 0
-}
-```
-
----
-
-## Runtime request middlewares
-
-Register a custom request hook at runtime (the "dynamic interceptor" escape hatch). `target` is `'all'` or an endpoint name (`'cms'`, `'report'`, …). Returns an unsubscribe.
-
-```ts
-const off = sdk.addRequestMiddleware('all', (options, ctx) => {
-  options.headers.set('X-Experiment', 'variant-b')
-})
-// later
-off()
-```
-
----
-
-## Mock mode
-
-While the backend is under development, `mock: true` makes every domain service resolve from a local fake dataset and never touch the network.
-
-```ts
-const sdk = createCmsSDK({ endpoints: { cms: 'http://x' }, mock: true })
-
-await sdk.content.list({ type: 'Mt5Account' })  // fake data
-sdk.setMock(false)                               // switch to real backend at runtime
-```
-
----
-
-## Project structure
-
-```
-src/
-├── core/                       # Stable foundation
-│   ├── createCmsSDK.ts         # Facade entry point (builds everything)
-│   ├── createApi.ts            # ofetch factory + auth/refresh/error hooks
-│   ├── errors.ts               # CmsError (normalised error shape)
-│   ├── sdk.type.ts             # Core public types (ICmsSDK, ICmsSDKOptions, …)
-│   └── credentials/            # TokenManager + storage adapters
-├── services/                   # 5 domain services (stateless, call $Fetch)
-│   ├── auth/                   # login / logout / OAuth refresh (confirmed BE)
-│   ├── content/                # CRUD + actions over /api/v1/content
-│   ├── rules/                  # rule CRUD + trigger/condition builders
-│   ├── executions/             # read-only execution feed
-│   └── settings/               # monitored groups
-├── stores/                     # 5 Pinia setup stores + persistence plugin
-├── server/                     # h3 handlers (auth proxies + token/persist)
-├── common/
-│   ├── constants/              # UPPER_SNAKE const objects (no hardcoding)
-│   ├── helpers/                # formatPrice / computeSpread / categoryLabel
-│   └── utils/                  # SDK-internal utilities (clone, casing)
-├── nuxt.ts                     # Nuxt module (registers $cms + stores + persistence)
-└── index.ts                    # Public barrel exports
-```
-
-Layering rule: `stores` → `services` → `core` (createApi/TokenManager) → `common` (constants/helpers/utils). Nothing reaches upward.
-
-## Development
-
-```bash
-pnpm install
-pnpm test        # vitest
-pnpm typecheck   # tsc --noEmit
-pnpm build       # vite build → dist/
-```
-
-## License
-
-See [LICENSE](./LICENSE). Published to the public npm registry — see
-[docs/npm-publishing.md](./docs/npm-publishing.md) for the release pipeline.

package/dist/chunks/{_shared-DdBWuPm_.js → _shared-DZlTUzoa.js}

@@ -1,4 +1,4 @@
-import { a as COOKIE_DEFAULTS } from './storage.constant--64BDSPW.js';
+import { a as COOKIE_DEFAULTS } from './storage.constant-CVWam5ls.js';
 import { useRuntimeConfig } from '#imports';
 
 const TOKEN_COOKIE_OPTIONS = {
@@ -24,4 +24,4 @@ function readSdkConfig(event) {
 }
 
 export { TOKEN_COOKIE_OPTIONS as T, readSdkConfig as r };
-//# sourceMappingURL=_shared-DdBWuPm_.js.map
+//# sourceMappingURL=_shared-DZlTUzoa.js.map

package/dist/chunks/{_shared-DdBWuPm_.js.map → _shared-DZlTUzoa.js.map}

@@ -1 +1 @@
-{"version":3,"file":"_shared-DdBWuPm_.js","sources":["../../src/server/auth/_shared.ts"],"sourcesContent":["import {\n  COOKIE_DEFAULTS,\n  REFRESH_TOKEN_STORAGE_KEY,\n  TOKEN_STORAGE_KEY,\n} from '../../common/constants/storage.constant';\nimport type { RequestCasing, ResponseCasing } from '../../common/constants/http.constant';\nimport { useRuntimeConfig } from '#imports';\n\n/** Cookie options for the httpOnly access-token cookie (server-side set). */\nexport const TOKEN_COOKIE_OPTIONS = {\n  httpOnly: COOKIE_DEFAULTS.HTTP_ONLY,\n  secure: COOKIE_DEFAULTS.SECURE,\n  sameSite: COOKIE_DEFAULTS.SAME_SITE.toLowerCase() as 'lax',\n  path: COOKIE_DEFAULTS.PATH,\n  maxAge: COOKIE_DEFAULTS.MAX_AGE_SECONDS,\n};\n\nexport { TOKEN_STORAGE_KEY, REFRESH_TOKEN_STORAGE_KEY };\n\n/**\n * Resolve the CMS backend URL + client id from the module options the Nuxt\n * module stored on `runtimeConfig.public.cmsSdkOptions` (mirrors the plugin\n * resolution). Runs inside the consumer's Nitro server where `useRuntimeConfig`\n * is auto-imported.\n */\nexport function readSdkConfig(event: unknown): {\n  cmsUrl: string;\n  clientId: string;\n  /** Default portal id for portal-scoped flows (module option `cmsSdk.portal`). */\n  portal?: string;\n  requestCasing?: RequestCasing;\n  responseCasing?: ResponseCasing;\n} {\n  const config = useRuntimeConfig(event) as { public?: Record<string, any> } | undefined;\n  const pub = (config?.public ?? {}) as Record<string, any>;\n  const opts = (pub.cmsSdkOptions ?? {}) as {\n    endpoints?: Record<string, string>;\n    clientId?: string;\n    portal?: string;\n    requestCasing?: RequestCasing;\n    responseCasing?: ResponseCasing;\n  };\n  const cmsUrl = pub[opts.endpoints?.cms ?? 'cmsUrl'];\n  const clientId = pub[opts.clientId ?? 'clientId'];\n  return {\n    cmsUrl,\n    clientId,\n    portal: opts.portal,\n    requestCasing: opts.requestCasing,\n    responseCasing: opts.responseCasing,\n  };\n}\n"],"names":[],"mappings":";;;AASO,MAAM,oBAAA,GAAuB;AAAA,EAClC,UAAU,eAAA,CAAgB,SAAA;AAAA,EAC1B,QAAQ,eAAA,CAAgB,MAAA;AAAA,EACxB,QAAA,EAAU,eAAA,CAAgB,SAAA,CAAU,WAAA,EAAY;AAAA,EAChD,MAAM,eAAA,CAAgB,IAAA;AAAA,EACtB,QAAQ,eAAA,CAAgB;AAC1B;AAUO,SAAS,cAAc,KAAA,EAO5B;AACA,EAAA,MAAM,MAAA,GAAS,iBAAiB,KAAK,CAAA;AACrC,EAAA,MAAM,GAAA,GAAO,MAAA,EAAQ,MAAA,IAAU,EAAC;AAChC,EAAA,MAAM,IAAA,GAAQ,GAAA,CAAI,aAAA,IAAiB,EAAC;AAOpC,EAAA,MAAM,MAAA,GAAS,GAAA,CAAI,IAAA,CAAK,SAAA,EAAW,OAAO,QAAQ,CAAA;AAClD,EAAA,MAAM,QAAA,GAAW,GAAA,CAAI,IAAA,CAAK,QAAA,IAAY,UAAU,CAAA;AAChD,EAAA,OAAO;AAAA,IACL,MAAA;AAAA,IACA,QAAA;AAAA,IACA,QAAQ,IAAA,CAAK,MAAA;AAAA,IACb,eAAe,IAAA,CAAK,aAAA;AAAA,IACpB,gBAAgB,IAAA,CAAK;AAAA,GACvB;AACF;;;;"}
+{"version":3,"file":"_shared-DZlTUzoa.js","sources":["../../src/server/auth/_shared.ts"],"sourcesContent":["import {\n  COOKIE_DEFAULTS,\n  REFRESH_TOKEN_STORAGE_KEY,\n  TOKEN_STORAGE_KEY,\n} from '../../common/constants/storage.constant';\nimport type { RequestCasing, ResponseCasing } from '../../common/constants/http.constant';\nimport { useRuntimeConfig } from '#imports';\n\n/** Cookie options for the httpOnly access-token cookie (server-side set). */\nexport const TOKEN_COOKIE_OPTIONS = {\n  httpOnly: COOKIE_DEFAULTS.HTTP_ONLY,\n  secure: COOKIE_DEFAULTS.SECURE,\n  sameSite: COOKIE_DEFAULTS.SAME_SITE.toLowerCase() as 'lax',\n  path: COOKIE_DEFAULTS.PATH,\n  maxAge: COOKIE_DEFAULTS.MAX_AGE_SECONDS,\n};\n\nexport { TOKEN_STORAGE_KEY, REFRESH_TOKEN_STORAGE_KEY };\n\n/**\n * Resolve the CMS backend URL + client id from the module options the Nuxt\n * module stored on `runtimeConfig.public.cmsSdkOptions` (mirrors the plugin\n * resolution). Runs inside the consumer's Nitro server where `useRuntimeConfig`\n * is auto-imported.\n */\nexport function readSdkConfig(event: unknown): {\n  cmsUrl: string;\n  clientId: string;\n  /** Default portal id for portal-scoped flows (module option `cmsSdk.portal`). */\n  portal?: string;\n  requestCasing?: RequestCasing;\n  responseCasing?: ResponseCasing;\n} {\n  const config = useRuntimeConfig(event) as { public?: Record<string, any> } | undefined;\n  const pub = (config?.public ?? {}) as Record<string, any>;\n  const opts = (pub.cmsSdkOptions ?? {}) as {\n    endpoints?: Record<string, string>;\n    clientId?: string;\n    portal?: string;\n    requestCasing?: RequestCasing;\n    responseCasing?: ResponseCasing;\n  };\n  const cmsUrl = pub[opts.endpoints?.cms ?? 'cmsUrl'];\n  const clientId = pub[opts.clientId ?? 'clientId'];\n  return {\n    cmsUrl,\n    clientId,\n    portal: opts.portal,\n    requestCasing: opts.requestCasing,\n    responseCasing: opts.responseCasing,\n  };\n}\n"],"names":[],"mappings":";;;AASO,MAAM,oBAAA,GAAuB;AAAA,EAClC,UAAU,eAAA,CAAgB,SAAA;AAAA,EAC1B,QAAQ,eAAA,CAAgB,MAAA;AAAA,EACxB,QAAA,EAAU,eAAA,CAAgB,SAAA,CAAU,WAAA,EAAY;AAAA,EAChD,MAAM,eAAA,CAAgB,IAAA;AAAA,EACtB,QAAQ,eAAA,CAAgB;AAC1B;AAUO,SAAS,cAAc,KAAA,EAO5B;AACA,EAAA,MAAM,MAAA,GAAS,iBAAiB,KAAK,CAAA;AACrC,EAAA,MAAM,GAAA,GAAO,MAAA,EAAQ,MAAA,IAAU,EAAC;AAChC,EAAA,MAAM,IAAA,GAAQ,GAAA,CAAI,aAAA,IAAiB,EAAC;AAOpC,EAAA,MAAM,MAAA,GAAS,GAAA,CAAI,IAAA,CAAK,SAAA,EAAW,OAAO,QAAQ,CAAA;AAClD,EAAA,MAAM,QAAA,GAAW,GAAA,CAAI,IAAA,CAAK,QAAA,IAAY,UAAU,CAAA;AAChD,EAAA,OAAO;AAAA,IACL,MAAA;AAAA,IACA,QAAA;AAAA,IACA,QAAQ,IAAA,CAAK,MAAA;AAAA,IACb,eAAe,IAAA,CAAK,aAAA;AAAA,IACpB,gBAAgB,IAAA,CAAK;AAAA,GACvB;AACF;;;;"}

package/dist/chunks/{storage.constant--64BDSPW.js → storage.constant-CVWam5ls.js}

@@ -10,6 +10,7 @@ const COOKIE_DEFAULTS = {
 };
 const STORE_PERSIST_KEY = {
   AUTH: "cms-auth-v1",
+  AUTHZ: "cms-authz-v1",
   CONTENT: "cms-content-v1",
   RULES: "cms-rules-v1",
   EXECUTIONS: "cms-executions-v1",
@@ -41,4 +42,4 @@ const COOKIE_SAME_SITE = {
 };
 
 export { COOKIE_SAME_SITE as C, PERSIST_KEY as P, REFRESH_TOKEN_STORAGE_KEY as R, STORE_PERSIST_KEY as S, TOKEN_STORAGE_KEY as T, COOKIE_DEFAULTS as a, PERSIST_ALLOWED_KEYS as b, PERSIST_MAX_BYTES as c, PERSIST_PREFIX as d, STORAGE_NAME as e };
-//# sourceMappingURL=storage.constant--64BDSPW.js.map
+//# sourceMappingURL=storage.constant-CVWam5ls.js.map

package/dist/chunks/storage.constant-CVWam5ls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.constant-CVWam5ls.js","sources":["../../src/common/constants/storage.constant.ts"],"sourcesContent":["/**\n * Token storage constants — the single source for the storage key so the\n * memory/localStorage/cookie adapters never drift apart.\n */\nexport const TOKEN_STORAGE_KEY = 'cms_access_token' as const;\n\n/**\n * Refresh-token cookie key. Stored as an httpOnly cookie (parallel to the access\n * token) so the SDK can silently rotate the access token when it expires.\n */\nexport const REFRESH_TOKEN_STORAGE_KEY = 'cms_refresh_token' as const;\n\n/** Cookie adapter defaults (overridable via `credentials.cookie`). */\nexport const COOKIE_DEFAULTS = {\n  MAX_AGE_SECONDS: 60 * 60 * 24 * 30, // 30 days\n  PATH: '/',\n  SECURE: true,\n  SAME_SITE: 'Lax',\n  HTTP_ONLY: true,\n} as const;\n\n/** Pinia persistence keys (versioned for schema migration). */\nexport const STORE_PERSIST_KEY = {\n  AUTH: 'cms-auth-v1',\n  AUTHZ: 'cms-authz-v1',\n  CONTENT: 'cms-content-v1',\n  RULES: 'cms-rules-v1',\n  EXECUTIONS: 'cms-executions-v1',\n  SETTINGS: 'cms-settings-v1',\n  LLM: 'cms-llm-v1',\n  LLM_PROVIDERS: 'cms-llm-providers-v1',\n  BARS: 'cms-bars-v1',\n  HISTORY: 'cms-history-v1',\n  KALSHI: 'cms-kalshi-v1',\n  GOV: 'cms-gov-v1',\n  PEOPLE: 'cms-people-v1',\n} as const;\n\n/**\n * Internal cookie persistence (replaces pinia-plugin-persistedstate).\n *\n * Each persisted state → its own cookie `${PERSIST_KEY.<store>}.${field}`.\n * The common `/api/cms-sdk/persist` endpoint may only set keys in\n * `PERSIST_ALLOWED_KEYS` (single source of truth, shared by the plugin + the\n * endpoint). The token key is always excluded as a belt-and-suspenders guard.\n */\nexport const PERSIST_PREFIX = 'cms-persist-' as const;\n\nexport const PERSIST_KEY = {\n  AUTH: 'cms-persist-auth',\n} as const;\n\n/** Max bytes per persisted cookie value (~4KB cookie cap, with headroom). */\nexport const PERSIST_MAX_BYTES = 3500;\n\n/** Allowlist of cookie keys the persist endpoint may set. */\nexport const PERSIST_ALLOWED_KEYS = [`${PERSIST_KEY.AUTH}.authUser`] as const;\n\n/**\n * Storage backend names accepted by `TokenManager`. Kept in sync with\n * `IStorageName` in `core/credentials/credential.type.ts`. The\n * `httpOnlyBridge` value is the recommended production backend (delegates\n * to a Nuxt server route).\n */\nexport const STORAGE_NAME = {\n  MEMORY: 'memory',\n  LOCAL_STORAGE: 'localStorage',\n  COOKIE: 'cookie',\n  HTTP_ONLY_BRIDGE: 'httpOnlyBridge',\n} as const;\nexport type StorageName = (typeof STORAGE_NAME)[keyof typeof STORAGE_NAME];\n\n/**\n * `Cookie SameSite` values (RFC 6265). Used by `cookieStorage` and the\n * SDK Nuxt module when setting the httpOnly access-token cookie. Mirrors\n * the `CookieSameSite` type in `core/credentials/storages/cookieStorage.ts`.\n */\nexport const COOKIE_SAME_SITE = {\n  STRICT: 'Strict',\n  LAX: 'Lax',\n  NONE: 'None',\n} as const;\nexport type CookieSameSite = (typeof COOKIE_SAME_SITE)[keyof typeof COOKIE_SAME_SITE];\n"],"names":[],"mappings":"AAIO,MAAM,iBAAA,GAAoB;AAM1B,MAAM,yBAAA,GAA4B;AAGlC,MAAM,eAAA,GAAkB;AAAA,EAC7B,eAAA,EAAiB,EAAA,GAAK,EAAA,GAAK,EAAA,GAAK,EAAA;AAAA;AAAA,EAChC,IAAA,EAAM,GAAA;AAAA,EACN,MAAA,EAAQ,IAAA;AAAA,EACR,SAAA,EAAW,KAAA;AAAA,EACX,SAAA,EAAW;AACb;AAGO,MAAM,iBAAA,GAAoB;AAAA,EAC/B,IAAA,EAAM,aAAA;AAAA,EACN,KAAA,EAAO,cAAA;AAAA,EACP,OAAA,EAAS,gBAAA;AAAA,EACT,KAAA,EAAO,cAAA;AAAA,EACP,UAAA,EAAY,mBAAA;AAAA,EACZ,QAAA,EAAU,iBAAA;AAAA,EACV,GAAA,EAAK,YAAA;AAAA,EACL,aAAA,EAAe,sBAAA;AAAA,EACf,IAAA,EAAM,aAAA;AAAA,EACN,OAAA,EAAS,gBAAA;AAAA,EACT,MAAA,EAAQ,eAAA;AAAA,EACR,GAAA,EAAK,YAAA;AAAA,EACL,MAAA,EAAQ;AACV;AAUO,MAAM,cAAA,GAAiB;AAEvB,MAAM,WAAA,GAAc;AAAA,EACzB,IAAA,EAAM;AACR;AAGO,MAAM,iBAAA,GAAoB;AAG1B,MAAM,oBAAA,GAAuB,CAAC,CAAA,EAAG,WAAA,CAAY,IAAI,CAAA,SAAA,CAAW;AAQ5D,MAAM,YAAA,GAAe;AAAA,EAC1B,MAAA,EAAQ,QAAA;AAAA,EACR,aAAA,EAAe,cAAA;AAAA,EACf,MAAA,EAAQ,QAAA;AAAA,EACR,gBAAA,EAAkB;AACpB;AAQO,MAAM,gBAAA,GAAmB;AAAA,EAC9B,MAAA,EAAQ,QAAA;AAAA,EACR,GAAA,EAAK,KAAA;AAAA,EACL,IAAA,EAAM;AACR;;;;"}

package/dist/common/constants/storage.constant.d.ts

@@ -19,6 +19,7 @@ export declare const COOKIE_DEFAULTS: {
 /** Pinia persistence keys (versioned for schema migration). */
 export declare const STORE_PERSIST_KEY: {
     readonly AUTH: "cms-auth-v1";
+    readonly AUTHZ: "cms-authz-v1";
     readonly CONTENT: "cms-content-v1";
     readonly RULES: "cms-rules-v1";
     readonly EXECUTIONS: "cms-executions-v1";

package/dist/common/constants/storage.constant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.constant.d.ts","sourceRoot":"","sources":["../../../src/common/constants/storage.constant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAG,kBAA2B,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAG,mBAA4B,CAAC;AAEtE,sEAAsE;AACtE,eAAO,MAAM,eAAe;;;;;;CAMlB,CAAC;AAEX,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;CAapB,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAG,cAAuB,CAAC;AAEtD,eAAO,MAAM,WAAW;;CAEd,CAAC;AAEX,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,6DAA6D;AAC7D,eAAO,MAAM,oBAAoB,wCAA4C,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,YAAY;;;;;CAKf,CAAC;AACX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE3E;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;CAInB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC"}
+{"version":3,"file":"storage.constant.d.ts","sourceRoot":"","sources":["../../../src/common/constants/storage.constant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAG,kBAA2B,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAG,mBAA4B,CAAC;AAEtE,sEAAsE;AACtE,eAAO,MAAM,eAAe;;;;;;CAMlB,CAAC;AAEX,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;CAcpB,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAG,cAAuB,CAAC;AAEtD,eAAO,MAAM,WAAW;;CAEd,CAAC;AAEX,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,6DAA6D;AAC7D,eAAO,MAAM,oBAAoB,wCAA4C,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,YAAY;;;;;CAKf,CAAC;AACX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE3E;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;CAInB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC"}