@devopsplaybook.io/common-web 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-27
+
+### Added
+
+- Initial Nuxt 4 layer package with shared design tokens and app-shell styles.
+- Loading, alert, navigation, and offline-banner components.
+- Theme, app-height, and offline-status composables.
+- Shared browser services for authentication, configuration, preferences,
+  refresh intervals, user initialization, and timeouts.
+- Vitest coverage against the packed package and a Nuxt playground.

package/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+## Local checks
+
+Use Node.js 22 and run the repository checks before opening a pull request:
+
+```sh
+npm ci
+npm run lint
+npm test
+npm run build
+```
+
+The tests consume the generated npm tarball, not only the working tree.
+`npm run build` checks the publish file list and builds the Nuxt playground.
+
+## Scope and compatibility
+
+Keep the layer limited to UI and browser behavior that is shared by multiple
+applications. Do not move app-domain components into this package. Components
+must retain their accessibility semantics, and Vue APIs used by raw library
+sources must be explicitly imported.
+
+The supported framework peer dependency is Nuxt 4. A Nuxt major upgrade needs
+a playground build and packed-tarball validation before the peer range changes.
+
+## Pull requests and releases
+
+Use conventional commit titles and include a summary and test plan in the PR.
+Keep releases semantic and update `package.json` and `CHANGELOG.md` together.
+The `Main Build` workflow publishes a version to public npm only when that
+version does not already exist. Do not publish manually from a developer
+machine.
+
+The first package PR uses equivalent local checks because the shared PR
+workflow expects `package.json` to exist on `main`; subsequent PRs use the
+shared npm PR workflow.

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, DevOpsPlaybook
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# @devopsplaybook.io/common-web
+
+A small, no-build Nuxt 4 layer containing shared design tokens, UI components,
+composables, and browser services for DevOpsPlaybook web applications.
+
+## Quick start
+
+```sh
+npm install @devopsplaybook.io/common-web
+```
+
+Extend the layer from your Nuxt configuration:
+
+```ts
+export default defineNuxtConfig({
+  extends: ["@devopsplaybook.io/common-web"],
+});
+```
+
+Layer components and composables are auto-imported by Nuxt. The package ships
+raw Vue and TypeScript sources; your app's Nuxt build compiles them. Nuxt 4 is
+required. The `playground/` directory demonstrates a consuming app.
+
+## Components
+
+| Component | Purpose |
+| --- | --- |
+| `<Loading size="small" />` | Accessible loading indicator; `size` is `small` or `large`. |
+| `<AlertMessages />` | Accessible live region displaying messages emitted on `EventBus`. |
+| `<AppNavigation :links="links" />` | Navigation shell with a named `brand` slot and configurable links (`label`, `to`, optional `icon` and `active`). |
+| `<OfflineBanner />` | Announces offline status and accepts replacement content through its default slot. |
+
+`AlertMessages` listens for `EventTypes.ALERT_MESSAGE` events. Its payload is
+`{ text, type?, durationMs? }`; the default display duration is five seconds.
+`handleError(error)` logs the error and emits a corresponding error alert.
+
+## Composables and services
+
+- `useTheme()` persists `light`/`dark` preferences in `localStorage` and applies
+  `data-theme` to the document root. Use `setTheme("system")` to return to the
+  operating-system preference.
+- `useAppHeight()` updates `--app-height` from `visualViewport` when available
+  and cleans up resize listeners on unmount.
+- `useOfflineStatus()` returns a reactive `isOnline` ref.
+- Browser services are available through package deep imports, for example
+  `@devopsplaybook.io/common-web/services/AuthService`.
+- `createAuthenticationStore()` returns the Pinia store definition; `Pinia`
+  must be available in the consuming app.
+
+The canonical auth storage key is `auth_token`. During this compatibility
+release, `AUTH_TOKEN` and `AUTH_TOKEN_KEY` are read and migrated to the
+canonical key. Tokens remain in `localStorage`, matching existing applications.
+
+## Tokens and app-shell styles
+
+The layer loads `assets/css/tokens.css` and `assets/css/app-shell.css`.
+Tokens include `--color-*`, `--space-*`, `--text-*`, `--radius-*`,
+`--shadow-*`, `--header-height`, and `--app-height`. Dark mode can be selected
+with `data-theme="dark"` or comes from `prefers-color-scheme` when no explicit
+light preference is set.
+
+Load app-specific CSS after the layer and redefine only the values you need:
+
+```css
+:root {
+  --color-primary: #145da0;
+  --header-height: 4.5rem;
+}
+```
+
+## Overriding a component
+
+Nuxt gives app-local components priority over layer components. Add a component
+with the same name under your app's `components/` directory, for example
+`components/Loading.vue`, and it replaces the layer's `<Loading />` without
+forking or modifying this package. App-specific navigation items are passed
+through the `links` prop rather than embedded in the layer.
+
+Deep imports are also available for tooling and tests that do not run inside a
+Nuxt app:
+
+```ts
+import Loading from "@devopsplaybook.io/common-web/components/Loading.vue";
+```
+
+## Compatibility and release policy
+
+This release supports Nuxt `^4.0.0` and Pinia `^2.0.0 || ^3.0.0`. Nuxt 3
+applications (including Telepathy) are not supported.
+
+For a Nuxt major upgrade, update the peer dependency, build the playground with
+the new major, test all exported components/composables from the packed
+tarball, and verify a scratch consumer can extend the layer before releasing.
+Keep releases semantic: patch for fixes, minor for backwards-compatible
+features, and major for breaking API or framework changes. The merge workflow
+publishes a new public npm version when the package version is not already
+published; bump `package.json` manually on the release PR.
+
+The initial bootstrap PR uses a repository-local workflow that runs install,
+audit, lint, packed-package tests, and the playground build. This is necessary
+because the shared PR workflow compares against `origin/main:package.json`,
+which does not exist before this first package change. Once the manifest is on
+`main`, PRs use the shared npm PR workflow; main builds always use the shared
+publish workflow.
+
+## Development
+
+```sh
+npm ci
+npm run lint
+npm test
+npm run build
+npm run dev
+```
+
+`npm test` packs the library and runs component and service tests against that
+archive. `npm run build` validates its contents and builds the playground.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution and release details.

package/assets/css/app-shell.css

@@ -0,0 +1,36 @@
+#page-layout {
+  display: grid;
+  grid-template-rows: auto minmax(0, 1fr);
+  min-height: var(--app-height, 100dvh);
+}
+
+#page-alert-messages {
+  position: fixed;
+  right: var(--space-xl, 2rem);
+  bottom: var(--space-xl, 2rem);
+  z-index: 1000;
+  max-width: min(80vw, 36rem);
+}
+
+@keyframes dpb-fade {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes dpb-blink {
+  50% {
+    opacity: 0.35;
+  }
+}
+
+.dpb-fade-in {
+  animation: dpb-fade 180ms ease-out;
+}
+
+.dpb-blink {
+  animation: dpb-blink 1s ease-in-out infinite;
+}

package/assets/css/tokens.css

@@ -0,0 +1,81 @@
+:root {
+  color-scheme: light;
+  --color-primary: #c62828;
+  --color-primary-hover: #a61f1f;
+  --color-text: #171717;
+  --color-text-muted: #5f6368;
+  --color-text-inverse: #fff;
+  --color-surface: #fff;
+  --color-surface-raised: #f5f5f5;
+  --color-surface-message: #fff9c4;
+  --color-surface-message-info: #c7e5c8;
+  --color-border: #d6d6d6;
+  --color-success: #2e7d32;
+  --color-error: #c62828;
+  --color-warning: #8a5a00;
+
+  --space-xs: 0.25rem;
+  --space-sm: 0.5rem;
+  --space-base: 1rem;
+  --space-md: 1.25rem;
+  --space-lg: 1.5rem;
+  --space-xl: 2rem;
+  --space-2xl: 3rem;
+
+  --text-xs: 0.75rem;
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.25rem;
+  --text-2xl: 1.5rem;
+
+  --radius-sm: 0.25rem;
+  --radius-md: 0.375rem;
+  --radius-lg: 0.5rem;
+  --radius-full: 9999px;
+
+  --shadow-sm: 0 1px 2px rgb(0 0 0 / 10%);
+  --shadow-md: 0 4px 12px rgb(0 0 0 / 15%);
+  --shadow-lg: 0 8px 24px rgb(0 0 0 / 20%);
+
+  --header-height: 4rem;
+  --app-height: 100dvh;
+}
+
+:root[data-theme="dark"] {
+  color-scheme: dark;
+  --color-text: #e0e0e0;
+  --color-text-muted: #b0b0b0;
+  --color-text-inverse: #fff;
+  --color-surface: #1a1a2e;
+  --color-surface-raised: #25253a;
+  --color-surface-message: #3a3520;
+  --color-surface-message-info: #1c3a1d;
+  --color-border: #44445a;
+  --color-success: #43a047;
+  --color-error: #e53935;
+  --color-warning: #f0b429;
+  --shadow-sm: 0 1px 2px rgb(0 0 0 / 30%);
+  --shadow-md: 0 4px 12px rgb(0 0 0 / 40%);
+  --shadow-lg: 0 8px 24px rgb(0 0 0 / 50%);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    color-scheme: dark;
+    --color-text: #e0e0e0;
+    --color-text-muted: #b0b0b0;
+    --color-text-inverse: #fff;
+    --color-surface: #1a1a2e;
+    --color-surface-raised: #25253a;
+    --color-surface-message: #3a3520;
+    --color-surface-message-info: #1c3a1d;
+    --color-border: #44445a;
+    --color-success: #43a047;
+    --color-error: #e53935;
+    --color-warning: #f0b429;
+    --shadow-sm: 0 1px 2px rgb(0 0 0 / 30%);
+    --shadow-md: 0 4px 12px rgb(0 0 0 / 40%);
+    --shadow-lg: 0 8px 24px rgb(0 0 0 / 50%);
+  }
+}

package/components/AlertMessages.vue

@@ -0,0 +1,77 @@
+<template>
+  <div role="status" aria-live="polite" class="alert-messages">
+    <div v-for="message in messages" :key="message.id">
+      <div
+        :class="message.type ? `message message-${message.type}` : 'message'"
+      >
+        <span class="message-text">
+          <b v-if="message.type">{{ message.type }}</b>
+          {{ message.text }}
+        </span>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { onMounted, onUnmounted, ref } from "vue";
+import { EventBus, EventTypes, type AlertMessage } from "../composables/EventBus";
+
+interface DisplayMessage extends AlertMessage {
+  id: number;
+}
+
+const messages = ref<DisplayMessage[]>([]);
+const timers = new Set<ReturnType<typeof setTimeout>>();
+let nextId = 1;
+
+function dismiss(id: number): void {
+  const index = messages.value.findIndex((message) => message.id === id);
+  if (index !== -1) messages.value.splice(index, 1);
+}
+
+function handleAlert(message: AlertMessage): void {
+  const entry = { ...message, id: nextId++ };
+  messages.value.push(entry);
+  const timer = setTimeout(() => {
+    timers.delete(timer);
+    dismiss(entry.id);
+  }, message.durationMs || 5000);
+  timers.add(timer);
+}
+
+onMounted(() => EventBus.on(EventTypes.ALERT_MESSAGE, handleAlert));
+onUnmounted(() => {
+  EventBus.off(EventTypes.ALERT_MESSAGE, handleAlert);
+  for (const timer of timers) clearTimeout(timer);
+  timers.clear();
+});
+</script>
+
+<style>
+.message {
+  display: flex;
+  align-items: center;
+  padding: var(--space-base, 1rem);
+  margin: var(--space-base, 1rem);
+  color: var(--color-text-inverse, #fff);
+  background-color: #546e7a;
+}
+
+.message-text {
+  flex: 1;
+}
+
+.message-info,
+.message-success {
+  background-color: var(--color-success, #2e7d32);
+}
+
+.message-warning {
+  background-color: var(--color-warning, #8a5a00);
+}
+
+.message-error {
+  background-color: var(--color-error, #c62828);
+}
+</style>

package/components/AppNavigation.vue

@@ -0,0 +1,59 @@
+<template>
+  <nav class="app-navigation" aria-label="Main navigation">
+    <div class="app-navigation-brand">
+      <slot name="brand" />
+    </div>
+    <ul class="app-navigation-links">
+      <li v-for="link in links" :key="link.to">
+        <a :href="link.to" :aria-current="link.active ? 'page' : undefined">
+          <span v-if="link.icon" :class="link.icon" aria-hidden="true" />
+          {{ link.label }}
+        </a>
+      </li>
+    </ul>
+    <slot />
+  </nav>
+</template>
+
+<script setup lang="ts">
+interface AppNavigationLink {
+  label: string;
+  to: string;
+  icon?: string;
+  active?: boolean;
+}
+
+defineProps<{ links: AppNavigationLink[] }>();
+</script>
+
+<style>
+.app-navigation {
+  display: flex;
+  align-items: center;
+  gap: var(--space-base, 1rem);
+  min-height: var(--header-height, 4rem);
+  padding-inline: var(--space-base, 1rem);
+  color: var(--color-text, inherit);
+  background: var(--color-surface, transparent);
+}
+
+.app-navigation-brand {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+}
+
+.app-navigation-links {
+  display: flex;
+  align-items: center;
+  gap: var(--space-sm, 0.5rem);
+  padding: 0;
+  margin: 0;
+  list-style: none;
+}
+
+.app-navigation a {
+  color: inherit;
+  text-decoration: none;
+}
+</style>

package/components/Loading.vue

@@ -0,0 +1,67 @@
+<template>
+  <div
+    class="loading-indicator"
+    :class="{ 'loading-indicator-small': size === 'small' }"
+    role="status"
+    aria-live="polite"
+    :aria-label="label"
+  />
+</template>
+
+<script setup lang="ts">
+withDefaults(defineProps<{ size?: "small" | "large"; label?: string }>(), {
+  size: "large",
+  label: "Loading",
+});
+</script>
+
+<style>
+.loading-indicator {
+  --loading-color: currentColor;
+  --loading-gradient: no-repeat linear-gradient(var(--loading-color) 0 0);
+  width: 15%;
+  min-width: 2rem;
+  margin: 20% auto;
+  aspect-ratio: 1;
+  background:
+    var(--loading-gradient) 0% 50%,
+    var(--loading-gradient) 50% 50%,
+    var(--loading-gradient) 100% 50%;
+  background-size: 20% 100%;
+  animation: dpb-loading 2s infinite linear;
+}
+
+.loading-indicator-small {
+  width: 3rem;
+  margin-top: 0.5rem;
+  margin-bottom: 0.5rem;
+}
+
+@keyframes dpb-loading {
+  0%,
+  100% {
+    background-size:
+      20% 100%,
+      20% 100%,
+      20% 100%;
+  }
+  33% {
+    background-size:
+      20% 10%,
+      20% 100%,
+      20% 100%;
+  }
+  50% {
+    background-size:
+      20% 100%,
+      20% 10%,
+      20% 100%;
+  }
+  66% {
+    background-size:
+      20% 100%,
+      20% 100%,
+      20% 10%;
+  }
+}
+</style>

package/components/OfflineBanner.vue

@@ -0,0 +1,20 @@
+<template>
+  <div v-if="!isOnline" class="offline-banner" role="status" aria-live="polite">
+    <slot>You are offline — showing cached data</slot>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { useOfflineStatus } from "../composables/useOfflineStatus";
+
+const { isOnline } = useOfflineStatus();
+</script>
+
+<style>
+.offline-banner {
+  padding: var(--space-sm, 0.5rem) var(--space-base, 1rem);
+  color: var(--color-text-inverse, #fff);
+  background: var(--color-warning, #8a5a00);
+  text-align: center;
+}
+</style>

package/composables/EventBus.ts

@@ -0,0 +1,43 @@
+import mitt from "mitt";
+
+export interface AlertMessage {
+  type?: "info" | "success" | "warning" | "error" | string;
+  text: string;
+  durationMs?: number;
+}
+
+interface AppEvents {
+  ALERT_MESSAGE: AlertMessage;
+  AUTH_UPDATED: void;
+}
+
+export const EventTypes = {
+  ALERT_MESSAGE: "ALERT_MESSAGE",
+  AUTH_UPDATED: "AUTH_UPDATED",
+} as const;
+
+export type EventType = (typeof EventTypes)[keyof typeof EventTypes];
+
+export const EventBus = mitt<AppEvents>();
+
+export function handleError(error: unknown): void {
+  console.error(error);
+  let text = error instanceof Error ? error.message : String(error);
+
+  if (typeof error === "object" && error !== null && "response" in error) {
+    const response = error.response;
+    if (
+      typeof response === "object" &&
+      response !== null &&
+      "data" in response &&
+      typeof response.data === "object" &&
+      response.data !== null &&
+      "error" in response.data &&
+      typeof response.data.error === "string"
+    ) {
+      text = response.data.error;
+    }
+  }
+
+  EventBus.emit(EventTypes.ALERT_MESSAGE, { type: "error", text });
+}

package/composables/useAppHeight.ts

@@ -0,0 +1,19 @@
+import { onMounted, onUnmounted } from "vue";
+
+export function useAppHeight(): void {
+  function updateAppHeight(): void {
+    const height = window.visualViewport?.height ?? window.innerHeight;
+    document.documentElement.style.setProperty("--app-height", `${height}px`);
+  }
+
+  onMounted(() => {
+    updateAppHeight();
+    window.addEventListener("resize", updateAppHeight);
+    window.visualViewport?.addEventListener("resize", updateAppHeight);
+  });
+
+  onUnmounted(() => {
+    window.removeEventListener("resize", updateAppHeight);
+    window.visualViewport?.removeEventListener("resize", updateAppHeight);
+  });
+}

package/composables/useOfflineStatus.ts

@@ -0,0 +1,22 @@
+import { onMounted, onUnmounted, ref } from "vue";
+
+export function useOfflineStatus() {
+  const isOnline = ref(true);
+
+  function updateStatus(): void {
+    isOnline.value = navigator.onLine;
+  }
+
+  onMounted(() => {
+    updateStatus();
+    window.addEventListener("online", updateStatus);
+    window.addEventListener("offline", updateStatus);
+  });
+
+  onUnmounted(() => {
+    window.removeEventListener("online", updateStatus);
+    window.removeEventListener("offline", updateStatus);
+  });
+
+  return { isOnline };
+}

package/composables/useTheme.ts

@@ -0,0 +1,56 @@
+import { computed, onMounted, onUnmounted, ref } from "vue";
+
+export type ThemePreference = "light" | "dark" | "system";
+
+const THEME_KEY = "UI_THEME";
+
+export function useTheme() {
+  const preference = ref<ThemePreference>("system");
+  const isDark = computed(() => preference.value === "dark");
+  let mediaQuery: MediaQueryList | undefined;
+
+  function applyTheme(): void {
+    if (typeof document === "undefined") return;
+
+    const prefersDark = mediaQuery?.matches ?? false;
+    const theme =
+      preference.value === "system"
+        ? prefersDark
+          ? "dark"
+          : "light"
+        : preference.value;
+    document.documentElement.setAttribute("data-theme", theme);
+  }
+
+  function setTheme(theme: ThemePreference): void {
+    preference.value = theme;
+    if (typeof localStorage !== "undefined") {
+      if (theme === "system") localStorage.removeItem(THEME_KEY);
+      else localStorage.setItem(THEME_KEY, theme);
+    }
+    applyTheme();
+  }
+
+  function toggleTheme(): void {
+    setTheme(isDark.value ? "light" : "dark");
+  }
+
+  function handleSystemThemeChange(): void {
+    if (preference.value === "system") applyTheme();
+  }
+
+  onMounted(() => {
+    const storedTheme = localStorage.getItem(THEME_KEY);
+    preference.value =
+      storedTheme === "light" || storedTheme === "dark" ? storedTheme : "system";
+    mediaQuery = window.matchMedia?.("(prefers-color-scheme: dark)");
+    mediaQuery?.addEventListener?.("change", handleSystemThemeChange);
+    applyTheme();
+  });
+
+  onUnmounted(() => {
+    mediaQuery?.removeEventListener?.("change", handleSystemThemeChange);
+  });
+
+  return { preference, isDark, setTheme, toggleTheme };
+}

package/nuxt.config.ts

@@ -0,0 +1,8 @@
+import { fileURLToPath } from "node:url";
+
+export default defineNuxtConfig({
+  css: [
+    fileURLToPath(new URL("./assets/css/tokens.css", import.meta.url)),
+    fileURLToPath(new URL("./assets/css/app-shell.css", import.meta.url)),
+  ],
+});

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@devopsplaybook.io/common-web",
+  "version": "0.1.0",
+  "description": "Shared Nuxt layer for DevOpsPlaybook web applications",
+  "license": "ISC",
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "exports": {
+    ".": "./nuxt.config.ts",
+    "./components/*": "./components/*",
+    "./composables/*": "./composables/*",
+    "./services/*": "./services/*",
+    "./stores/*": "./stores/*"
+  },
+  "files": [
+    "nuxt.config.ts",
+    "assets",
+    "components",
+    "composables",
+    "services",
+    "stores",
+    "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "nuxi dev playground",
+    "lint": "oxlint components composables services stores tests scripts playground vitest.config.ts nuxt.config.ts",
+    "test": "node scripts/test-packed.mjs",
+    "build": "node scripts/build-package.mjs"
+  },
+  "peerDependencies": {
+    "nuxt": "^4.0.0",
+    "pinia": "^2.0.0 || ^3.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.12.2",
+    "jwt-decode": "^4.0.0",
+    "mitt": "^3.0.1"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.9",
+    "@vitest/coverage-v8": "^5.0.2",
+    "@vue/test-utils": "^2.5.1",
+    "jsdom": "^30.1.1",
+    "nuxt": "4.5.2",
+    "oxlint": "^1.85.0",
+    "pinia": "^3.0.4",
+    "vitest": "^5.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/services/AuthService.ts

@@ -0,0 +1,58 @@
+import { jwtDecode } from "jwt-decode";
+
+export const AUTH_TOKEN_KEY = "auth_token";
+const LEGACY_TOKEN_KEYS = ["AUTH_TOKEN", "AUTH_TOKEN_KEY"] as const;
+
+export interface AuthHeaders {
+  headers?: {
+    Authorization: string;
+  };
+}
+
+export class AuthService {
+  static async isAuthenticated(): Promise<boolean> {
+    return Boolean(await AuthService.getToken());
+  }
+
+  static async saveToken(token: string): Promise<void> {
+    localStorage.setItem(AUTH_TOKEN_KEY, token);
+    for (const key of LEGACY_TOKEN_KEYS) localStorage.removeItem(key);
+  }
+
+  static async removeToken(_token?: string): Promise<void> {
+    localStorage.removeItem(AUTH_TOKEN_KEY);
+    for (const key of LEGACY_TOKEN_KEYS) localStorage.removeItem(key);
+  }
+
+  static async getToken(): Promise<string | null> {
+    let token = localStorage.getItem(AUTH_TOKEN_KEY);
+
+    if (!token) {
+      for (const legacyKey of LEGACY_TOKEN_KEYS) {
+        token = localStorage.getItem(legacyKey);
+        if (token) {
+          localStorage.setItem(AUTH_TOKEN_KEY, token);
+          localStorage.removeItem(legacyKey);
+          break;
+        }
+      }
+    }
+
+    if (!token) return null;
+
+    const decoded = jwtDecode<{ exp?: number }>(token);
+    if (typeof decoded.exp === "number" && decoded.exp <= Date.now() / 1000) {
+      await AuthService.removeToken();
+      return null;
+    }
+
+    return token;
+  }
+
+  static async getAuthHeader(): Promise<AuthHeaders> {
+    const token = await AuthService.getToken();
+    return token
+      ? { headers: { Authorization: `Bearer ${token}` } }
+      : {};
+  }
+}

package/services/Config.ts

@@ -0,0 +1,9 @@
+export interface AppConfig {
+  SERVER_URL: string;
+}
+
+export default class Config {
+  static async get(): Promise<AppConfig> {
+    return { SERVER_URL: "/api" };
+  }
+}

package/services/PreferencesService.ts

@@ -0,0 +1,13 @@
+export const PreferencesService = {
+  get(key: string): string | null {
+    return localStorage.getItem(key);
+  },
+
+  set(key: string, value: string): void {
+    localStorage.setItem(key, value);
+  },
+
+  remove(key: string): void {
+    localStorage.removeItem(key);
+  },
+};

package/services/RefreshIntervalService.ts

@@ -0,0 +1,12 @@
+export class RefreshIntervalService {
+  static readonly KEY = "REFRESH_INTERVAL";
+  static readonly DEFAULT = "10000";
+
+  static get(): string {
+    return localStorage.getItem(RefreshIntervalService.KEY) ?? RefreshIntervalService.DEFAULT;
+  }
+
+  static set(value: string): void {
+    localStorage.setItem(RefreshIntervalService.KEY, value);
+  }
+}

package/services/Timeout.ts

@@ -0,0 +1,7 @@
+export class Timeout {
+  static wait(duration: number): Promise<void> {
+    return new Promise((resolve) => {
+      setTimeout(resolve, duration);
+    });
+  }
+}

package/services/UserService.ts

@@ -0,0 +1,12 @@
+import axios from "axios";
+import Config from "./Config";
+
+export class UserService {
+  static async isInitialized(): Promise<boolean> {
+    const config = await Config.get();
+    const response = await axios.get<{ initialized: boolean }>(
+      `${config.SERVER_URL}/users/status/initialization`,
+    );
+    return response.data.initialized;
+  }
+}

package/stores/AuthenticationStore.ts

@@ -0,0 +1,25 @@
+import { acceptHMRUpdate, defineStore } from "pinia";
+import { AuthService } from "../services/AuthService";
+
+export function createAuthenticationStore() {
+  return defineStore("AuthenticationStore", {
+    state: () => ({
+      isAuthenticated: false,
+    }),
+
+    actions: {
+      async ensureAuthenticated(): Promise<boolean> {
+        this.isAuthenticated = await AuthService.isAuthenticated();
+        return this.isAuthenticated;
+      },
+    },
+  });
+}
+
+export const AuthenticationStore = createAuthenticationStore();
+
+if (import.meta.hot) {
+  import.meta.hot.accept(
+    acceptHMRUpdate(AuthenticationStore, import.meta.hot),
+  );
+}