@alliance-droid/status-feedback-system 3.0.0 → 4.0.0

package/README.md

@@ -14,7 +14,8 @@ This is the **client package** — UI components that talk to a [status-feedback
 │  │ StatusPage        │──┼───────┼──│ /api/status        │  │
 │  │ FeedbackButton    │  │       │  │ /api/feedback      │  │
 │  │ DevFeedback       │  │       │  │ /api/incidents     │  │
-│  │ FeedbackBoard     │  │       │  │ /api/board         │  │
+│  │ Feedback board    │  │       │  │ /api/board         │  │
+│  │  (composable)     │  │       │  │                    │  │
 │  └───────────────────┘  │       │  └────────────────────┘  │
 │                         │       │           │              │
 │  npm package            │       │  MSSQL + Azure Blob      │
@@ -152,32 +153,70 @@ Standalone feedback form — embed it wherever you need it.
 | `onSuccess` | `() => void` | — | Called after successful submission |
 | `onError` | `(error: string) => void` | — | Called on submission error |
 
-### FeedbackBoard
+### Feedback board (composable)
 
-Public feedback board with voting, category filtering, and admin responses.
+> 📖 **Full integration guide:** [docs/custom-feedback-integration.md](docs/custom-feedback-integration.md) — composing the parts into your own shell, status management via `getAuthToken`, list restyling, and the not-configured fallback.
+
+The board is composed from parts around **one shared state** (`createFeedbackBoard`), so it drops into your own layout/shell — app rails, breadcrumb, a right-hand detail panel, whatever you have.
 
 ```svelte
-<FeedbackBoard
-  apiUrl="https://status-admin.example.com"
-  apiKey="sf_abc123..."
-  title="Feature Requests"
-  showSubmit={true}
-  submitCategories={['Bug', 'Feature Request', 'Improvement']}
-  categoryConfig={{
-    Bug: { icon: 'fa-solid fa-bug', label: 'Bugs', description: 'Something broken' },
-    'Feature Request': { icon: 'fa-solid fa-lightbulb', label: 'Ideas' },
-  }}
-/>
+<script lang="ts">
+  import {
+    createFeedbackBoard,
+    FeedbackSidebar,
+    FeedbackList,
+    FeedbackDetail,
+    FeedbackSubmitForm,
+    type BoardItem,
+  } from '@alliance-droid/status-feedback-system';
+
+  let { data } = $props();
+  const board = createFeedbackBoard({
+    apiUrl: 'https://status-admin.example.com',
+    apiKey: 'sf_abc123...',
+    userEmail: data.user?.email,
+    getAuthToken: () => auth.getAccessToken(), // optional — enables status management
+    categoryConfig: {
+      Bug: { icon: 'fa-solid fa-bug', label: 'Bugs' },
+      'Feature Request': { icon: 'fa-solid fa-lightbulb', label: 'Ideas' },
+    },
+  });
+
+  let selected = $state<BoardItem | null>(null);
+</script>
+
+<YourSidebar><FeedbackSidebar {board} /></YourSidebar>
+<YourMain><FeedbackList {board} onSelect={(i) => (selected = i)} /></YourMain>
+<YourRail>
+  {#if selected}<FeedbackDetail {board} item={selected} />{/if}
+</YourRail>
+<!-- Render <FeedbackSubmitForm {board} /> wherever you want submission. -->
 ```
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
+`createFeedbackBoard(options)` returns a reactive `FeedbackBoardState` (items, categories, filters, voting, `loadTransitions`/`setStatus`, …) shared by every sub-component.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
 | `apiUrl` | `string` | required | Admin backend URL |
-| `apiKey` | `string` | required | Project API key |
-| `title` | `string` | `'Feedback Board'` | Header title |
-| `showSubmit` | `boolean` | `true` | Show inline submit form |
-| `submitCategories` | `string[]` | `[]` | Category options for submit form |
-| `categoryConfig` | `Record<string, { label?, icon?, description? }>` | `{}` | Customize sidebar categories |
+| `apiKey` | `string` | required | Project API key (`sf_…`) |
+| `userEmail` | `string` | — | Authenticated user (required to submit feedback/replies) |
+| `categoryConfig` | `Record<string, { label?, icon?, description? }>` | `{}` | Relabel / add icons to sidebar categories |
+| `getAuthToken` | `() => string \| Promise<string \| null>` | — | Bearer token so privileged users can set status (see below) |
+| `pageSize` | `number` | `50` | Items per page |
+
+Exported parts: `createFeedbackBoard`, `FeedbackSidebar`, `FeedbackList`, `FeedbackItem`, `FeedbackDetail`, `FeedbackSubmitForm`.
+
+Categories are fixed by the system (**Bug**, **Feature Request**) — `categoryConfig` only relabels or adds icons.
+
+#### Setting status (Admin / ProductOwner)
+
+When you pass `getAuthToken`, a signed-in **Admin** or **ProductOwner** can change an item's status from the board (via the status badge → menu) — Open → Considering → Accepted, or a decline with a reason — no trip to the admin dashboard.
+
+- `getAuthToken` must return the user's **Alliance OIDC access token** whose audience covers **`status-feedback-admin`** (an *id token*, whose `aud` is your app's client id, is rejected). It's called on demand; return `null` for anonymous / non-privileged users and the control simply won't appear.
+- The token travels as `Authorization: Bearer …` to the admin backend, which **verifies it against the IdP** and derives the user's roles. Authorization (per-project access + which transitions a role may make, including reason prompts on declines/reopens) is enforced **server-side** by the same logic as the dashboard — the client never decides permissions.
+- The available transitions are returned by the backend per item, so the menu always reflects exactly what that user may do.
+
+> Security note: the project `apiKey` alone never grants status changes — it only identifies the project. Every mutation additionally requires a valid IdP token, so the public board key stays safe to embed.
 
 ### DevFeedback
 
@@ -253,10 +292,16 @@ import {
 ```typescript
 // Components
 import {
-  StatusPage, StatusBanner, FeedbackForm, FeedbackButton,
-  FeedbackBoard, DevFeedback,
-  StatusIndicator, UptimeBar, IncidentTimeline, SystemCard,
+  StatusPage, StatusBanner, FeedbackForm, FeedbackButton, DevFeedback,
+  StatusIndicator, UptimeBar, IncidentTimeline, SystemCard, PasteImageInput,
+} from '@alliance-droid/status-feedback-system';
+
+// Feedback board (composable)
+import {
+  createFeedbackBoard,
+  FeedbackSidebar, FeedbackList, FeedbackItem, FeedbackDetail, FeedbackSubmitForm,
 } from '@alliance-droid/status-feedback-system';
+import type { FeedbackBoardState, FeedbackBoardOptions, CategoryConfig } from '@alliance-droid/status-feedback-system';
 
 // API Client
 import { createStatusClient } from '@alliance-droid/status-feedback-system';

package/dist/api.d.ts

@@ -11,7 +11,7 @@
  *
  *   const { systems, incidents } = await client.getStatus();
  */
-import type { System, Incident, StatusHistoryEntry, Feedback, FeedbackResponse } from './types.js';
+import type { System, Incident, StatusHistoryEntry, Feedback, FeedbackResponse, PublicStatus } from './types.js';
 export interface StatusClientConfig {
     /** Base URL of the status-feedback-admin app */
     apiUrl: string;
@@ -41,6 +41,8 @@ export interface BoardItem {
     message: string;
     email: string | null;
     status: string;
+    /** Coarse public bucket for display (server projection of the internal status). */
+    publicStatus: PublicStatus;
     votes: number;
     adminResponse: string | null;
     responseCount: number;
@@ -51,6 +53,30 @@ export interface BoardData {
     total: number;
     categories: BoardCategory[];
 }
+/** A status a privileged user may move an item to, and whether it needs a reason. */
+export interface BoardTransition {
+    /** Raw internal status value to submit. */
+    status: string;
+    /** Human label for the menu. */
+    display: string;
+    /** When true, the user must supply a reason to make this transition. */
+    requiresReason: boolean;
+}
+/** The current status of a board item plus the transitions the caller may make. */
+export interface BoardTransitions {
+    current: {
+        status: string;
+        display: string;
+        publicStatus: PublicStatus;
+    };
+    targets: BoardTransition[];
+}
+/** Result of applying a status change from the board. */
+export interface BoardStatusUpdate {
+    id: string;
+    status: string;
+    publicStatus: PublicStatus;
+}
 export interface StatusClient {
     /** Get current system statuses */
     getStatus(): Promise<StatusData>;
@@ -80,6 +106,17 @@ export interface StatusClient {
         limit?: number;
         offset?: number;
     }): Promise<BoardData>;
+    /**
+     * Status transitions the token's user may make on a board item. Requires an
+     * Alliance id token; the backend returns an empty `targets` list for users
+     * without a qualifying role.
+     */
+    getBoardTransitions(feedbackId: string, token: string): Promise<BoardTransitions>;
+    /** Set a board item's status (privileged). Requires an Alliance id token. */
+    updateBoardStatus(feedbackId: string, data: {
+        status: string;
+        reason?: string;
+    }, token: string): Promise<BoardStatusUpdate>;
     /** Vote on a feedback item */
     vote(feedbackId: string, direction?: 'up' | 'down'): Promise<{
         votes: number;

package/dist/api.js

@@ -87,6 +87,18 @@ export function createStatusClient(config) {
             const qs = params.toString();
             return request(`/api/board${qs ? `?${qs}` : ''}`);
         },
+        async getBoardTransitions(feedbackId, token) {
+            return request(`/api/board/feedback/${feedbackId}/transitions`, {
+                headers: { Authorization: `Bearer ${token}` },
+            });
+        },
+        async updateBoardStatus(feedbackId, data, token) {
+            return request(`/api/board/feedback/${feedbackId}/status`, {
+                method: 'PATCH',
+                headers: { Authorization: `Bearer ${token}` },
+                body: JSON.stringify(data),
+            });
+        },
         async vote(feedbackId, direction = 'up') {
             return request('/api/board/vote', {
                 method: 'POST',

package/dist/components/DevFeedback.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
 	import { createStatusClient, type StatusClient } from '../api.js';
+	import { FEEDBACK_CATEGORIES } from '../types.js';
 	import PasteImageInput from './shared/PasteImageInput.svelte';
 	import {
 		Card,
@@ -363,7 +364,7 @@
 			await getClient().submitFeedback({
 				title: formTitle.trim() || undefined,
 				message: formMessage.trim(),
-				category: formType === 'bug' ? 'bug' : 'feature',
+				category: formType === 'bug' ? FEEDBACK_CATEGORIES[0] : FEEDBACK_CATEGORIES[1],
 				email: userEmail,
 				pageUrl: window.location.href,
 				metadata,