@abgov/nx-adsp 13.18.0-beta.10 → 13.18.0-beta.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abgov/nx-adsp",
-  "version": "13.18.0-beta.10",
+  "version": "13.18.0-beta.12",
   "license": "Apache-2.0",
   "main": "src/index.js",
   "description": "Government of Alberta - Nx plugin for ADSP apps.",

package/src/generators/vue-app/files/AGENTS.md__tmpl__

@@ -176,7 +176,7 @@ from **`<%= goaImportPath %>`**, not hand-rolled markup:
 
 | Component | Purpose |
 |---|---|
-| `AppSideMenu` | `goa-work-side-menu`. Takes `heading`/`primaryItems`/`secondaryItems`/`accountItems` props (each item: `{ label, to?, icon?, badge?, current? }`) and emits `itemClick` — it doesn't know about routing or auth, so `App.vue` computes `current`/handles the click itself. `App.vue` currently only populates `accountItems` (a single Sign in/out item); add real nav items to `primaryItems`/`secondaryItems` as routes are added. Also owns the skip-to-main-content landmark for this layout — `AppLayout` deliberately doesn't duplicate it. Also takes an optional `#topbar` slot — a slim row above the routed content, for something like a notification bell; only renders when given content, unused by default |
+| `AppSideMenu` | `goa-work-side-menu`. Takes `heading`/`primaryItems`/`secondaryItems`/`accountItems` props (each item: `{ label, to?, icon?, badge?, current? }`) and emits `itemClick` — it doesn't know about routing or auth, so `App.vue` computes `current`/handles the click itself. `App.vue` currently only populates `accountItems` (a single Sign in/out item); add real nav items to `primaryItems`/`secondaryItems` as routes are added. **`icon` is effectively required** — `goa-work-side-menu-item` renders a blank item without it; use a GoA icon name (see [design.alberta.ca/components/icons](https://design.alberta.ca/components/icons)). Also owns the skip-to-main-content landmark for this layout — `AppLayout` deliberately doesn't duplicate it. Also takes an optional `#topbar` slot — a slim row above the routed content, for something like a notification bell; only renders when given content, unused by default |
 | `AppLayout` | The content gutter every view renders inside (see the key files table) |
 | `SessionExpiredBanner` | A `v-model:show` banner with `signIn`/`dismiss` emits. Bound to the `useSessionStore()` Pinia store (`src/stores/session.ts`), which `main.ts`'s `onAuthRefreshError` hook flips when the refresh token itself has expired |
 
@@ -234,20 +234,105 @@ mark what's meant to be edited.
    { path: '/queue', component: () => import('../views/QueueView.vue'), meta: { layout: 'wide' } }
    { path: '/apply', component: () => import('../views/ApplyView.vue'), meta: { layout: 'form' } }
    ```
-3. Add a nav link to `src/App.vue` if needed
+3. **For the `internal` layout: add a nav link to `src/App.vue`.** The generated shell only
+   populates `accountItems`; primary navigation lives in `primaryItems` (or `secondaryItems`).
+   `AppSideMenu` is purely presentational — it doesn't know about routing, so `App.vue` owns
+   `current` detection and the `itemClick` handler:
+
+   ```typescript
+   // In <script setup>:
+   import { computed } from 'vue';
+   import { RouterView, useRoute, useRouter } from 'vue-router';
+   // ...existing imports...
+
+   const route = useRoute();    // already in the generated App.vue
+   const router = useRouter();
+
+   // Icon names come from the GoA icon set: design.alberta.ca/components/icons
+   const primaryItems = computed(() => [
+     { label: 'Home',       to: '/',           icon: 'home',  current: route.path === '/' },
+     { label: 'My Feature', to: '/my-feature', icon: 'list',  current: route.path.startsWith('/my-feature') },
+   ]);
+
+   function onItemClick(item: { to?: string }) {
+     if (item.to) router.push(item.to);
+   }
+   ```
+
+   ```html
+   <!-- In <template>, add :primary-items and @item-click to <AppSideMenu>: -->
+   <AppSideMenu
+     heading="..."
+     :primary-items="primaryItems"
+     :account-items="accountItems"
+     @item-click="onItemClick"
+   >
+   ```
+
+   The `header` layout has no side menu — add route-level breadcrumbs or a secondary nav
+   directly inside the view component instead.
 
 ## Backend API calls (proxy setup)
 
-Use relative `/api/` paths — they route through Vite's dev proxy and nginx in production:
+Use relative `/api/` paths — they route through Vite's dev proxy and nginx in production.
+
+**Use `useApi()` for all API calls.** `apiFetch` automatically refreshes the token and adds
+`Authorization: Bearer` when the user is authenticated — you never need to do it at each
+call site.
 
 ```typescript
-// ✓ correct
-const res = await fetch('/api/v1/my-resource');
+import { useApi } from '../composables/useApi' // adjust depth for nested components (../../…)
+
+const { apiFetch } = useApi()
+
+// ✓ Any route — adds the token when authenticated, skips it when not
+const res = await apiFetch('/api/v1/my-resource')
 
-// ✗ wrong — bypasses proxy, won't work in production
-const res = await fetch('http://localhost:3333/my-service/v1/my-resource');
+// ✓ With a request body
+const res = await apiFetch('/api/v1/my-resource', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify(payload),
+})
+
+// ✗ Wrong path — bypasses proxy, won't work in production
+const res = await fetch('http://localhost:3333/<%= pairedProject || 'my-service' %>/v1/my-resource')
+```
+
+**Most routes require authentication.** The service mounts `/v1` with the anonymous passport
+strategy, so a bare request without a token reaches the router — but business routes also
+gate on `tenant` auth and will 401. `apiFetch` handles this automatically when signed in.
+
+**React to auth state for calls that require the user to be signed in.** Keycloak settles
+asynchronously; watch `kc.authenticated` rather than reading it once on mount:
+
+```typescript
+import { watch } from 'vue'
+import { useKeycloak } from '@dsb-norge/vue-keycloak-js'
+import { useApi } from '../composables/useApi'
+
+const kc = useKeycloak()
+const { apiFetch } = useApi()
+
+watch(
+  () => kc.authenticated,
+  async (authenticated) => {
+    if (!authenticated) return
+    try {
+      const res = await apiFetch('/api/v1/my-resource')
+      // ...
+    } catch {
+      // apiFetch rejects on network error or if the refresh token expired;
+      // the SessionExpiredBanner handles the latter via onAuthRefreshError.
+    }
+  },
+  { immediate: true },
+)
 ```
 
+`apiFetch` adds the token only when `kc.authenticated` is true — the watch ensures
+you call it only after auth has settled, not speculatively on mount.
+
 ## Testing
 
 Tests live alongside source files (`*.spec.ts` / `*.spec.vue`) and run with Vitest:

package/src/generators/vue-app/files/src/composables/useApi.ts__tmpl__

@@ -0,0 +1,21 @@
+import { useKeycloak } from '@dsb-norge/vue-keycloak-js'
+
+export function useApi() {
+  // Keep the reactive instance — do NOT destructure: `authenticated` and `keycloak`
+  // are plain values inside a reactive object and only populate asynchronously once
+  // Keycloak settles. Reading `kc.authenticated` at call time (inside apiFetch)
+  // always gets the current value; a destructured snapshot would freeze at setup time.
+  const kc = useKeycloak()
+
+  async function apiFetch(url: string, init: RequestInit = {}): Promise<Response> {
+    if (kc.authenticated) {
+      await kc.keycloak?.updateToken(30)
+      const headers = new Headers(init.headers)
+      headers.set('Authorization', `Bearer ${kc.keycloak?.token}`)
+      return fetch(url, { ...init, headers })
+    }
+    return fetch(url, init)
+  }
+
+  return { apiFetch }
+}

package/src/generators/vue-app/files/src/views/HomeView.vue__tmpl__

@@ -1,43 +1,42 @@
 <script setup lang="ts">
-import { ref, onMounted, watch } from 'vue';
-import { useKeycloak } from '@dsb-norge/vue-keycloak-js';
+import { ref, onMounted, watch } from 'vue'
+import { useKeycloak } from '@dsb-norge/vue-keycloak-js'
+import { useApi } from '../composables/useApi'
 
 // Keep the reactive instance — do NOT destructure (see App.vue): a destructured
-// `authenticated`/`keycloak` freezes at its setup-time value, so the private
-// fetch below would never see the user sign in and the bearer token stays undefined.
-const kc = useKeycloak();
-const publicResource = ref('Not retrieved — is the backend service running?');
-const privateResource = ref('Not retrieved — sign in first.');
+// `authenticated` freezes at its setup-time value, so the watch below would never
+// see the user sign in and apiFetch would always skip the token.
+const kc = useKeycloak()
+const { apiFetch } = useApi()
+const publicResource = ref('Not retrieved — is the backend service running?')
+const privateResource = ref('Not retrieved — sign in first.')
 
 onMounted(async () => {
   try {
-    const res = await fetch('/api/v1/public');
-    const data = await res.json();
-    publicResource.value = data.message;
+    const res = await apiFetch('/api/v1/public')
+    const data = await res.json()
+    publicResource.value = data.message
   } catch {
-    publicResource.value = 'Error loading public resource.';
+    publicResource.value = 'Error loading public resource.'
   }
-});
+})
 
 // React to authentication (which settles asynchronously and may flip after mount,
 // e.g. on return from the login redirect) rather than reading it once on mount.
 watch(
   () => kc.authenticated,
   async (authenticated) => {
-    if (!authenticated) return;
+    if (!authenticated) return
     try {
-      await kc.keycloak?.updateToken(30);
-      const res = await fetch('/api/v1/private', {
-        headers: { Authorization: `Bearer ${kc.keycloak?.token}` },
-      });
-      const data = await res.json();
-      privateResource.value = data.message;
+      const res = await apiFetch('/api/v1/private')
+      const data = await res.json()
+      privateResource.value = data.message
     } catch {
-      privateResource.value = 'Error loading private resource.';
+      privateResource.value = 'Error loading private resource.'
     }
   },
-  { immediate: true }
-);
+  { immediate: true },
+)
 </script>
 
 <template>

package/src/generators/vue-app/vue-app.spec.ts

@@ -297,6 +297,23 @@ describe('Vue App Generator', () => {
     expect(app).toContain('kc.keycloak?.login()');
   }, 30000);
 
+  it('generates a useApi composable that handles token refresh and auth headers', async () => {
+    await generator(host, options);
+    expect(host.exists('apps/test/src/composables/useApi.ts')).toBeTruthy();
+    const useApi = host.read('apps/test/src/composables/useApi.ts').toString();
+    // Token refresh and auth header injection are encapsulated here, not at each call site.
+    expect(useApi).toContain('updateToken');
+    expect(useApi).toContain('Authorization');
+    expect(useApi).toContain('apiFetch');
+
+    // HomeView delegates to the composable — raw token wiring must not leak into views.
+    const homeView = host.read('apps/test/src/views/HomeView.vue').toString();
+    expect(homeView).toContain('useApi');
+    expect(homeView).toContain('apiFetch');
+    expect(homeView).not.toContain('updateToken');
+    expect(homeView).not.toContain('Authorization');
+  }, 30000);
+
   it('index.html is at the Vite entry root and its mount target matches main.ts', async () => {
     await generator(host, options);
     // Vite's entry is <projectRoot>/index.html, not src/index.html — a template