@zeitvu97/cms-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 viettienlv97
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,478 @@
+# @zeitvu97/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 @zeitvu97/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',
+    '@zeitvu97/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 '@zeitvu97/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 '@zeitvu97/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 '@zeitvu97/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 '@zeitvu97/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 '@zeitvu97/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 '@zeitvu97/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
+
+MIT — see [LICENSE](./LICENSE).

package/dist/chunks/_shared-48T7q0V3.js

@@ -0,0 +1,26 @@
+import { a as COOKIE_DEFAULTS } from './storage.constant--64BDSPW.js';
+import { useRuntimeConfig } from '#imports';
+
+const TOKEN_COOKIE_OPTIONS = {
+  httpOnly: COOKIE_DEFAULTS.HTTP_ONLY,
+  secure: COOKIE_DEFAULTS.SECURE,
+  sameSite: COOKIE_DEFAULTS.SAME_SITE.toLowerCase(),
+  path: COOKIE_DEFAULTS.PATH,
+  maxAge: COOKIE_DEFAULTS.MAX_AGE_SECONDS
+};
+function readSdkConfig(event) {
+  const config = useRuntimeConfig(event);
+  const pub = config?.public ?? {};
+  const opts = pub.cmsSdkOptions ?? {};
+  const cmsUrl = pub[opts.endpoints?.cms ?? "cmsUrl"];
+  const clientId = pub[opts.clientId ?? "clientId"];
+  return {
+    cmsUrl,
+    clientId,
+    requestCasing: opts.requestCasing,
+    responseCasing: opts.responseCasing
+  };
+}
+
+export { TOKEN_COOKIE_OPTIONS as T, readSdkConfig as r };
+//# sourceMappingURL=_shared-48T7q0V3.js.map

package/dist/chunks/_shared-48T7q0V3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_shared-48T7q0V3.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  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    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    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,EAK5B;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;AAMpC,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,eAAe,IAAA,CAAK,aAAA;AAAA,IACpB,gBAAgB,IAAA,CAAK;AAAA,GACvB;AACF;;;;"}

package/dist/chunks/auth.constant-DO7ZmsKg.js

@@ -0,0 +1,68 @@
+const HTTP_HEADER = {
+  AUTHORIZATION: "Authorization",
+  DEVICE_ID: "DeviceID",
+  DEVICE_IP: "DeviceIP",
+  CLIENT_ID: "X-Client-Id",
+  USER_AGENT: "user-agent",
+  REQUEST_ID: "x-request-id",
+  /**
+   * Backend response-casing selector. Default backend casing is camelCase
+   * (omit the header); send `snake` to receive snake_case bodies.
+   */
+  RESPONSE_CASING: "x-response-casing",
+  /**
+   * Backend request-casing selector. Default is camelCase (omit the header);
+   * send `snake` to declare a snake_case request body.
+   */
+  REQUEST_CASING: "x-request-casing"
+};
+const RESPONSE_CASING_VALUE = {
+  SNAKE: "snake"
+};
+const SERIALIZATION_FORMAT = {
+  JSON: "json",
+  YAML: "yaml"
+};
+const HTTP_DEFAULTS = {
+  TIMEOUT_MS: 3e4,
+  RETRY: 0
+};
+const HTTP_RETRY_STATUS_CODES = [408, 425, 429, 500, 502, 503, 504];
+
+const AUTH_ENDPOINT = {
+  LOGIN: "/api/auth/login",
+  LOGOUT: "/api/auth/logout",
+  REFRESH: "/api/oauth/token",
+  /** User registry (GET /api/auth/users) — list of the CMS auth users. */
+  USERS: "/api/auth/users",
+  /** "Login with CBS" — init (PKCE verifier + state stay server-side). */
+  CBS_START: "/api/v1/auth/oauth/cbs/start",
+  /** "Login with CBS" — complete (exchange code → CMS session JWT). */
+  CBS_CALLBACK: "/api/v1/auth/oauth/cbs/callback",
+  /** IdP SSO — init (`GET /api/auth/{provider}/login?redirect_uri=…`). */
+  idpLogin: (provider) => `/api/auth/${provider}/login`,
+  /** IdP SSO — callback (`GET /api/auth/{provider}/callback?code&state&redirect_uri`). */
+  idpCallback: (provider) => `/api/auth/${provider}/callback`,
+  /** IdP SSO — link an already-authenticated user to the provider (needs Bearer). */
+  idpLink: (provider) => `/api/auth/${provider}/link`,
+  /** IdP SSO — unlink the provider from the current user (needs Bearer). */
+  idpUnlink: (provider) => `/api/auth/${provider}/unlink`
+};
+const AUTH_PROXY_PATH = {
+  LOGIN: "/login",
+  LOGOUT: "/logout",
+  REFRESH: "/refresh",
+  CBS_START: "/cbs-start",
+  CBS_CALLBACK: "/cbs-callback",
+  /** IdP SSO — init (query: `provider`, `redirect_uri`). */
+  IDP_LOGIN: "/idp-login",
+  /** IdP SSO — callback (query: `provider`, `code`, `state`, `redirect_uri`). */
+  IDP_CALLBACK: "/idp-callback",
+  /** IdP SSO — link (body: `{ provider }`; forwards the token cookie as Bearer). */
+  IDP_LINK: "/idp-link",
+  /** IdP SSO — unlink (query: `provider`; forwards the token cookie as Bearer). */
+  IDP_UNLINK: "/idp-unlink"
+};
+
+export { AUTH_PROXY_PATH as A, HTTP_DEFAULTS as H, RESPONSE_CASING_VALUE as R, SERIALIZATION_FORMAT as S, HTTP_RETRY_STATUS_CODES as a, HTTP_HEADER as b, AUTH_ENDPOINT as c };
+//# sourceMappingURL=auth.constant-DO7ZmsKg.js.map

package/dist/chunks/auth.constant-DO7ZmsKg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.constant-DO7ZmsKg.js","sources":["../../src/common/constants/http.constant.ts","../../src/common/constants/auth.constant.ts"],"sourcesContent":["/**\n * HTTP-layer constants shared by the core `createApi` factory.\n */\n\n/** Canonical request/response header names used across the SDK. */\nexport const HTTP_HEADER = {\n  AUTHORIZATION: 'Authorization',\n  DEVICE_ID: 'DeviceID',\n  DEVICE_IP: 'DeviceIP',\n  CLIENT_ID: 'X-Client-Id',\n  USER_AGENT: 'user-agent',\n  REQUEST_ID: 'x-request-id',\n  /**\n   * Backend response-casing selector. Default backend casing is camelCase\n   * (omit the header); send `snake` to receive snake_case bodies.\n   */\n  RESPONSE_CASING: 'x-response-casing',\n  /**\n   * Backend request-casing selector. Default is camelCase (omit the header);\n   * send `snake` to declare a snake_case request body.\n   */\n  REQUEST_CASING: 'x-request-casing',\n} as const;\n\n/** Supported response-casing values. camelCase is the backend default. */\nexport const RESPONSE_CASING_VALUE = {\n  CAMEL: 'camel',\n  SNAKE: 'snake',\n} as const;\nexport type ResponseCasing = (typeof RESPONSE_CASING_VALUE)[keyof typeof RESPONSE_CASING_VALUE];\nexport type RequestCasing = ResponseCasing;\n\n/**\n * Serialization format discriminator. Accepted by content / rules /\n * lenses list endpoints via `?format=json|yaml`.\n */\nexport const SERIALIZATION_FORMAT = {\n  JSON: 'json',\n  YAML: 'yaml',\n} as const;\nexport type SerializationFormat = (typeof SERIALIZATION_FORMAT)[keyof typeof SERIALIZATION_FORMAT];\n\n/** Default per-request tuning (overridable via `createCmsSDK` options). */\nexport const HTTP_DEFAULTS = {\n  TIMEOUT_MS: 30000,\n  RETRY: 0,\n} as const;\n\n/** Status codes eligible for automatic retry (transient failures). */\nexport const HTTP_RETRY_STATUS_CODES = [408, 425, 429, 500, 502, 503, 504] as const;\n","/**\n * Auth backend endpoints.\n *\n * The CMS backend exposes exactly three auth endpoints:\n *   - LOGIN    (POST /api/auth/login)   — confirmed against the real backend\n *   - LOGOUT   (POST /api/auth/logout)  — confirmed (real backend logout is POST)\n *   - REFRESH  (POST /api/oauth/token)  — confirmed — OAuth token endpoint;\n *                                         grant_type=refresh_token\n *\n * Path params are appended at call sites.\n */\nexport const AUTH_ENDPOINT = {\n  LOGIN: '/api/auth/login',\n  LOGOUT: '/api/auth/logout',\n  REFRESH: '/api/oauth/token',\n  /** User registry (GET /api/auth/users) — list of the CMS auth users. */\n  USERS: '/api/auth/users',\n  /** \"Login with CBS\" — init (PKCE verifier + state stay server-side). */\n  CBS_START: '/api/v1/auth/oauth/cbs/start',\n  /** \"Login with CBS\" — complete (exchange code → CMS session JWT). */\n  CBS_CALLBACK: '/api/v1/auth/oauth/cbs/callback',\n  /** IdP SSO — init (`GET /api/auth/{provider}/login?redirect_uri=…`). */\n  idpLogin: (provider: string): string => `/api/auth/${provider}/login`,\n  /** IdP SSO — callback (`GET /api/auth/{provider}/callback?code&state&redirect_uri`). */\n  idpCallback: (provider: string): string => `/api/auth/${provider}/callback`,\n  /** IdP SSO — link an already-authenticated user to the provider (needs Bearer). */\n  idpLink: (provider: string): string => `/api/auth/${provider}/link`,\n  /** IdP SSO — unlink the provider from the current user (needs Bearer). */\n  idpUnlink: (provider: string): string => `/api/auth/${provider}/unlink`,\n} as const;\n\n/**\n * Client→proxy route paths for token-lifecycle flows.\n *\n * When the Nuxt module is in use, login/logout/token route through the\n * app-origin server proxies (`/api/cms/*`) so the httpOnly cookies are\n * set/cleared/rotated atomically. These are the paths the auth service calls\n * on its `routeApi` (whose baseURL is `/api/cms`).\n */\nexport const AUTH_PROXY_PATH = {\n  LOGIN: '/login',\n  LOGOUT: '/logout',\n  REFRESH: '/refresh',\n  CBS_START: '/cbs-start',\n  CBS_CALLBACK: '/cbs-callback',\n  /** IdP SSO — init (query: `provider`, `redirect_uri`). */\n  IDP_LOGIN: '/idp-login',\n  /** IdP SSO — callback (query: `provider`, `code`, `state`, `redirect_uri`). */\n  IDP_CALLBACK: '/idp-callback',\n  /** IdP SSO — link (body: `{ provider }`; forwards the token cookie as Bearer). */\n  IDP_LINK: '/idp-link',\n  /** IdP SSO — unlink (query: `provider`; forwards the token cookie as Bearer). */\n  IDP_UNLINK: '/idp-unlink',\n} as const;\n"],"names":[],"mappings":"AAKO,MAAM,WAAA,GAAc;AAAA,EACzB,aAAA,EAAe,eAAA;AAAA,EACf,SAAA,EAAW,UAAA;AAAA,EACX,SAAA,EAAW,UAAA;AAAA,EACX,SAAA,EAAW,aAAA;AAAA,EACX,UAAA,EAAY,YAAA;AAAA,EACZ,UAAA,EAAY,cAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAKZ,eAAA,EAAiB,mBAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAKjB,cAAA,EAAgB;AAClB;AAGO,MAAM,qBAAA,GAAwB;AAAA,EAEnC,KAAA,EAAO;AACT;AAQO,MAAM,oBAAA,GAAuB;AAAA,EAClC,IAAA,EAAM,MAAA;AAAA,EACN,IAAA,EAAM;AACR;AAIO,MAAM,aAAA,GAAgB;AAAA,EAC3B,UAAA,EAAY,GAAA;AAAA,EACZ,KAAA,EAAO;AACT;AAGO,MAAM,uBAAA,GAA0B,CAAC,GAAA,EAAK,GAAA,EAAK,KAAK,GAAA,EAAK,GAAA,EAAK,KAAK,GAAG;;ACtClE,MAAM,aAAA,GAAgB;AAAA,EAC3B,KAAA,EAAO,iBAAA;AAAA,EACP,MAAA,EAAQ,kBAAA;AAAA,EACR,OAAA,EAAS,kBAAA;AAAA;AAAA,EAET,KAAA,EAAO,iBAAA;AAAA;AAAA,EAEP,SAAA,EAAW,8BAAA;AAAA;AAAA,EAEX,YAAA,EAAc,iCAAA;AAAA;AAAA,EAEd,QAAA,EAAU,CAAC,QAAA,KAA6B,CAAA,UAAA,EAAa,QAAQ,CAAA,MAAA,CAAA;AAAA;AAAA,EAE7D,WAAA,EAAa,CAAC,QAAA,KAA6B,CAAA,UAAA,EAAa,QAAQ,CAAA,SAAA,CAAA;AAAA;AAAA,EAEhE,OAAA,EAAS,CAAC,QAAA,KAA6B,CAAA,UAAA,EAAa,QAAQ,CAAA,KAAA,CAAA;AAAA;AAAA,EAE5D,SAAA,EAAW,CAAC,QAAA,KAA6B,CAAA,UAAA,EAAa,QAAQ,CAAA,OAAA;AAChE;AAUO,MAAM,eAAA,GAAkB;AAAA,EAC7B,KAAA,EAAO,QAAA;AAAA,EACP,MAAA,EAAQ,SAAA;AAAA,EACR,OAAA,EAAS,UAAA;AAAA,EACT,SAAA,EAAW,YAAA;AAAA,EACX,YAAA,EAAc,eAAA;AAAA;AAAA,EAEd,SAAA,EAAW,YAAA;AAAA;AAAA,EAEX,YAAA,EAAc,eAAA;AAAA;AAAA,EAEd,QAAA,EAAU,WAAA;AAAA;AAAA,EAEV,UAAA,EAAY;AACd;;;;"}