@alliance-droid/status-feedback-system 2.3.2 → 3.1.0

package/README.md

@@ -1,273 +1,275 @@
-# @alliance-droid/status-feedback-system
-
-Drop-in system status pages and user feedback components for SvelteKit apps.
-
-This is the **client package** — UI components that talk to a [status-feedback-admin](https://alliance.ghe.com/alliance/status-feedback-admin) backend via API. The admin app handles data storage, API key management, and the admin dashboard.
-
-## Architecture
-
-```
-┌─────────────────────────┐       ┌──────────────────────────┐
-│   Your SvelteKit App    │       │  status-feedback-admin   │
-│                         │       │                          │
-│  ┌───────────────────┐  │  API  │  ┌────────────────────┐  │
-│  │ StatusPage        │──┼───────┼──│ /api/status        │  │
-│  │ FeedbackButton    │  │       │  │ /api/feedback      │  │
-│  │ DevFeedback       │  │       │  │ /api/incidents     │  │
-│  │ FeedbackBoard     │  │       │  │ /api/board         │  │
-│  └───────────────────┘  │       │  └────────────────────┘  │
-│                         │       │           │              │
-│  npm package            │       │  MSSQL + Azure Blob      │
-└─────────────────────────┘       └──────────────────────────┘
-```
-
-## Setup
-
-### 1. Deploy the admin backend
-
-The admin app ([status-feedback-admin](https://alliance.ghe.com/alliance/status-feedback-admin)) provides the API, database, and admin dashboard. Deploy it first.
-
-Required env vars on the admin app:
-```bash
-MSSQL_CONNECTION_STRING=Server=...;Initial Catalog=StatusFeedback;...
-SESSION_SECRET=your-secret
-
-# Optional — stores screenshots in Azure Blob Storage instead of base64 in DB
-AZURE_FEEDBACK_BLOB_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
-AZURE_FEEDBACK_BLOB_CONTAINER=screenshots
-```
-
-### 2. Create a project and get an API key
-
-Log into the admin dashboard, create a project, and copy its API key (prefixed `sf_`).
-
-### 3. Install the client package
-
-```bash
-npm install @alliance-droid/status-feedback-system
-```
-
-**Peer dependencies:** `svelte ^5.0.0`, `@alliance-droid/svelte-component-library >=1.0.0`
-
-## Components
-
-### StatusPage
-
-Full status page with systems, incidents, and uptime history bars. Supports **self-fetching** (provide `apiUrl` + `apiKey`) or **pass-through** (provide data directly).
-
-```svelte
-<script>
-  import { StatusPage } from '@alliance-droid/status-feedback-system';
-</script>
-
-<!-- Self-fetching mode -->
-<StatusPage
-  projectName="My App"
-  apiUrl="https://status-admin.example.com"
-  apiKey="sf_abc123..."
-/>
-
-<!-- Pass-through mode -->
-<StatusPage
-  projectName="My App"
-  systems={data.systems}
-  incidents={data.incidents}
-  statusHistory={data.statusHistory}
-  showUptime={true}
-/>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `projectName` | `string` | required | Display name in the header |
-| `apiUrl` | `string` | — | Admin backend URL (self-fetching mode) |
-| `apiKey` | `string` | — | Project API key (self-fetching mode) |
-| `systems` | `System[]` | — | Pass-through: system data |
-| `incidents` | `Incident[]` | — | Pass-through: incident data |
-| `statusHistory` | `Record<string, StatusHistoryEntry[]>` | — | Pass-through: uptime data |
-| `showUptime` | `boolean` | `true` | Show 90-day uptime bars |
-
-### StatusBanner
-
-Compact inline status indicator — good for footers or nav bars.
-
-```svelte
-<StatusBanner
-  apiUrl="https://status-admin.example.com"
-  apiKey="sf_abc123..."
-  statusUrl="/status"
-/>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `systems` | `System[]` | — | Pass-through mode |
-| `apiUrl` | `string` | — | Self-fetching mode |
-| `apiKey` | `string` | — | Self-fetching mode |
-| `statusUrl` | `string` | — | Links to full status page (renders as `<a>`) |
-
-### FeedbackButton
-
-Floating action button with an embedded feedback form. Fixed position, bottom corner.
-
-```svelte
-<FeedbackButton
-  apiKey="sf_abc123..."
-  apiUrl="https://status-admin.example.com"
-  position="bottom-right"
-  categories={['Bug', 'Feature Request', 'General']}
-  userEmail={currentUser?.email}
-/>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `apiUrl` | `string` | required | Admin backend URL |
-| `apiKey` | `string` | required | Project API key |
-| `categories` | `string[]` | `['Bug', 'Feature Request', 'General']` | Category options |
-| `userEmail` | `string` | — | Pre-fill email field |
-| `position` | `'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Button position |
-
-### FeedbackForm
-
-Standalone feedback form — embed it wherever you need it.
-
-```svelte
-<FeedbackForm
-  apiKey="sf_abc123..."
-  apiUrl="https://status-admin.example.com"
-  categories={['Bug', 'Feature Request']}
-  userEmail={currentUser?.email}
-  onSuccess={() => toast('Thanks!')}
-  onError={(msg) => toast(msg, 'error')}
-/>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `apiUrl` | `string` | required | Admin backend URL |
-| `apiKey` | `string` | required | Project API key |
-| `categories` | `string[]` | `['Bug', 'Feature Request', 'General']` | Category options |
-| `userEmail` | `string` | — | Pre-fill email field |
-| `onSuccess` | `() => void` | — | Called after successful submission |
-| `onError` | `(error: string) => void` | — | Called on submission error |
-
-### FeedbackBoard
-
-Public feedback board with voting, category filtering, and admin responses.
-
-```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' },
-  }}
-/>
-```
-
-| Prop | 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 |
-
-### DevFeedback
-
-Developer feedback overlay for staging/preview environments. Activated via **Ctrl+right-click** anywhere on the page.
-
-Auto-captures: screenshots (via html2canvas), console errors, viewport size, current route, clicked element selector, and deployment context (Vercel env vars).
-
-```svelte
-<script>
-  import { DevFeedback } from '@alliance-droid/status-feedback-system';
-</script>
-
-<!-- In your root +layout.svelte -->
-<DevFeedback
-  apiUrl="https://status-admin.example.com"
-  apiKey="sf_abc123..."
-  boardUrl="/feedback"
-  userEmail={data.user?.email}
-/>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `apiUrl` | `string` | required | Admin backend URL |
-| `apiKey` | `string` | required | Project API key |
-| `enabled` | `boolean` | auto-detect | Override environment detection |
-| `boardUrl` | `string` | — | URL for "View Open Issues" link. Hidden if omitted. |
-| `userEmail` | `string` | — | Pre-fill email field (e.g. from logged-in user's session) |
-| `maxConsoleErrors` | `number` | `20` | Max console errors to capture |
-| `showOnboarding` | `boolean` | `true` | Show "Ctrl+right-click" toast on first visit |
-
-**Environment auto-detection:** Enabled on `localhost`, `127.0.0.1`, `*.local`, and Vercel preview deployments. Disabled in Vercel production. Override with the `enabled` prop or `PUBLIC_FEEDBACK_ENABLED` env var.
-
-**Screenshot storage:** If the admin backend has `AZURE_FEEDBACK_BLOB_CONNECTION_STRING` configured, screenshots are uploaded to Azure Blob Storage. Otherwise they're stored as base64 in the database.
-
-## API Client
-
-All components use a shared API client. You can also use it directly:
-
-```typescript
-import { createStatusClient } from '@alliance-droid/status-feedback-system';
-
-const client = createStatusClient({
-  apiUrl: 'https://status-admin.example.com',
-  apiKey: 'sf_abc123...',
-  fetch: event.fetch, // Optional: pass SvelteKit's fetch for SSR
-});
-
-const { systems, overallStatus } = await client.getStatus();
-const { incidents } = await client.getIncidents({ limit: 5, includeResolved: true });
-const { history } = await client.getUptime({ days: 90 });
-const feedback = await client.submitFeedback({ message: 'Great product!' });
-const { items, total, categories } = await client.getBoard({ sort: 'votes', status: 'open' });
-```
-
-## Shared Components
-
-Lower-level building blocks used by StatusPage — exported for custom layouts:
-
-```typescript
-import {
-  StatusIndicator,  // Status dot + label (operational/degraded/outage/maintenance)
-  UptimeBar,        // 90-day uptime bar chart
-  IncidentTimeline, // Chronological incident updates
-  SystemCard,       // Single system status card with uptime bar
-} from '@alliance-droid/status-feedback-system';
-```
-
-## All Exports
-
-```typescript
-// Components
-import {
-  StatusPage, StatusBanner, FeedbackForm, FeedbackButton,
-  FeedbackBoard, DevFeedback,
-  StatusIndicator, UptimeBar, IncidentTimeline, SystemCard,
-} from '@alliance-droid/status-feedback-system';
-
-// API Client
-import { createStatusClient } from '@alliance-droid/status-feedback-system';
-import type { StatusClient, StatusClientConfig } from '@alliance-droid/status-feedback-system';
-
-// Types
-import type {
-  System, Incident, IncidentUpdate, Feedback, FeedbackResponse,
-  SystemStatus, IncidentStatus, IncidentSeverity, FeedbackStatus,
-  StatusData, IncidentData, UptimeData, BoardData, BoardItem,
-} from '@alliance-droid/status-feedback-system';
-```
-
-## License
-
-Copyright © 2026 Alliance Technical Group. All rights reserved.
+# @alliance-droid/status-feedback-system
+
+Drop-in system status pages and user feedback components for SvelteKit apps.
+
+This is the **client package** — UI components that talk to a [status-feedback-admin](https://alliance.ghe.com/alliance/status-feedback-admin) backend via API. The admin app handles data storage, API key management, and the admin dashboard.
+
+## Architecture
+
+```
+┌─────────────────────────┐       ┌──────────────────────────┐
+│   Your SvelteKit App    │       │  status-feedback-admin   │
+│                         │       │                          │
+│  ┌───────────────────┐  │  API  │  ┌────────────────────┐  │
+│  │ StatusPage        │──┼───────┼──│ /api/status        │  │
+│  │ FeedbackButton    │  │       │  │ /api/feedback      │  │
+│  │ DevFeedback       │  │       │  │ /api/incidents     │  │
+│  │ FeedbackBoard     │  │       │  │ /api/board         │  │
+│  └───────────────────┘  │       │  └────────────────────┘  │
+│                         │       │           │              │
+│  npm package            │       │  MSSQL + Azure Blob      │
+└─────────────────────────┘       └──────────────────────────┘
+```
+
+## Setup
+
+### 1. Deploy the admin backend
+
+The admin app ([status-feedback-admin](https://alliance.ghe.com/alliance/status-feedback-admin)) provides the API, database, and admin dashboard. Deploy it first.
+
+Required env vars on the admin app:
+```bash
+MSSQL_CONNECTION_STRING=Server=...;Initial Catalog=StatusFeedback;...
+SESSION_SECRET=your-secret
+
+# Optional — stores screenshots in Azure Blob Storage instead of base64 in DB
+AZURE_FEEDBACK_BLOB_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
+AZURE_FEEDBACK_BLOB_CONTAINER=screenshots
+```
+
+### 2. Create a project and get an API key
+
+Log into the admin dashboard, create a project, and copy its API key (prefixed `sf_`).
+
+### 3. Install the client package
+
+```bash
+npm install @alliance-droid/status-feedback-system
+```
+
+**Peer dependencies:** `svelte ^5.0.0`, `@alliance-droid/svelte-component-library >=1.0.0`
+
+## Components
+
+### StatusPage
+
+Full status page with systems, incidents, and uptime history bars. Supports **self-fetching** (provide `apiUrl` + `apiKey`) or **pass-through** (provide data directly).
+
+```svelte
+<script>
+  import { StatusPage } from '@alliance-droid/status-feedback-system';
+</script>
+
+<!-- Self-fetching mode -->
+<StatusPage
+  projectName="My App"
+  apiUrl="https://status-admin.example.com"
+  apiKey="sf_abc123..."
+/>
+
+<!-- Pass-through mode -->
+<StatusPage
+  projectName="My App"
+  systems={data.systems}
+  incidents={data.incidents}
+  statusHistory={data.statusHistory}
+  showUptime={true}
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `projectName` | `string` | required | Display name in the header |
+| `apiUrl` | `string` | — | Admin backend URL (self-fetching mode) |
+| `apiKey` | `string` | — | Project API key (self-fetching mode) |
+| `systems` | `System[]` | — | Pass-through: system data |
+| `incidents` | `Incident[]` | — | Pass-through: incident data |
+| `statusHistory` | `Record<string, StatusHistoryEntry[]>` | — | Pass-through: uptime data |
+| `showUptime` | `boolean` | `true` | Show 90-day uptime bars |
+
+### StatusBanner
+
+Compact inline status indicator — good for footers or nav bars.
+
+```svelte
+<StatusBanner
+  apiUrl="https://status-admin.example.com"
+  apiKey="sf_abc123..."
+  statusUrl="/status"
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `systems` | `System[]` | — | Pass-through mode |
+| `apiUrl` | `string` | — | Self-fetching mode |
+| `apiKey` | `string` | — | Self-fetching mode |
+| `statusUrl` | `string` | — | Links to full status page (renders as `<a>`) |
+
+### FeedbackButton
+
+Floating action button with an embedded feedback form. Fixed position, bottom corner.
+
+```svelte
+<FeedbackButton
+  apiKey="sf_abc123..."
+  apiUrl="https://status-admin.example.com"
+  position="bottom-right"
+  categories={['Bug', 'Feature Request', 'General']}
+  userEmail={currentUser?.email}
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiUrl` | `string` | required | Admin backend URL |
+| `apiKey` | `string` | required | Project API key |
+| `categories` | `string[]` | `['Bug', 'Feature Request', 'General']` | Category options |
+| `userEmail` | `string` | — | Pre-fill email field |
+| `position` | `'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Button position |
+
+### FeedbackForm
+
+Standalone feedback form — embed it wherever you need it.
+
+```svelte
+<FeedbackForm
+  apiKey="sf_abc123..."
+  apiUrl="https://status-admin.example.com"
+  categories={['Bug', 'Feature Request']}
+  userEmail={currentUser?.email}
+  onSuccess={() => toast('Thanks!')}
+  onError={(msg) => toast(msg, 'error')}
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiUrl` | `string` | required | Admin backend URL |
+| `apiKey` | `string` | required | Project API key |
+| `categories` | `string[]` | `['Bug', 'Feature Request', 'General']` | Category options |
+| `userEmail` | `string` | — | Pre-fill email field |
+| `onSuccess` | `() => void` | — | Called after successful submission |
+| `onError` | `(error: string) => void` | — | Called on submission error |
+
+### FeedbackBoard
+
+Public feedback board with voting, category filtering, and admin responses.
+
+```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' },
+  }}
+/>
+```
+
+| Prop | 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 |
+
+### DevFeedback
+
+Feedback overlay for authorized users. Activated via **Ctrl+right-click** (Cmd+right-click on macOS) anywhere on the page.
+
+Auto-captures: screenshots (via html2canvas), console errors, viewport size, current route, clicked element selector, and deployment context (Vercel env vars).
+
+**Gating:** the widget shows only when `enabled` is `true` **and** `userEmail` is non-empty. `enabled` is the single gate — wire it to your own rule, typically a role/permission check. There is no environment auto-detection. See [docs/role-based-access.md](docs/role-based-access.md) for the recommended role-based setup and the pitfalls.
+
+```svelte
+<script>
+  import { DevFeedback } from '@alliance-droid/status-feedback-system';
+</script>
+
+<!-- In your root +layout.svelte -->
+<DevFeedback
+  apiUrl="https://status-admin.example.com"
+  apiKey="sf_abc123..."
+  boardUrl="/feedback"
+  userEmail={user?.email ?? ''}
+  enabled={userCanGiveFeedback}
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiUrl` | `string` | required | Admin backend URL |
+| `apiKey` | `string` | required | Project API key |
+| `enabled` | `boolean` | required | The only gate — wire to your role/permission check |
+| `userEmail` | `string` | required | Signed-in user's email. Empty string ⇒ renders nothing (anonymous feedback unsupported) |
+| `boardUrl` | `string` | — | URL for "View Open Issues" link. Hidden if omitted. |
+| `maxConsoleErrors` | `number` | `20` | Max console errors to capture |
+| `showOnboarding` | `boolean` | `true` | Show "Ctrl+right-click" toast on first visit |
+| `renderTokenEndpoint` | `string` | `/svc/internal/issue-render-token` | App endpoint that mints render tokens for screenshot capture |
+
+**Screenshot storage:** If the admin backend has `AZURE_FEEDBACK_BLOB_CONNECTION_STRING` configured, screenshots are uploaded to Azure Blob Storage. Otherwise they're stored as base64 in the database.
+
+## API Client
+
+All components use a shared API client. You can also use it directly:
+
+```typescript
+import { createStatusClient } from '@alliance-droid/status-feedback-system';
+
+const client = createStatusClient({
+  apiUrl: 'https://status-admin.example.com',
+  apiKey: 'sf_abc123...',
+  fetch: event.fetch, // Optional: pass SvelteKit's fetch for SSR
+});
+
+const { systems, overallStatus } = await client.getStatus();
+const { incidents } = await client.getIncidents({ limit: 5, includeResolved: true });
+const { history } = await client.getUptime({ days: 90 });
+const feedback = await client.submitFeedback({ message: 'Great product!' });
+const { items, total, categories } = await client.getBoard({ sort: 'votes', status: 'open' });
+```
+
+## Shared Components
+
+Lower-level building blocks used by StatusPage — exported for custom layouts:
+
+```typescript
+import {
+  StatusIndicator,  // Status dot + label (operational/degraded/outage/maintenance)
+  UptimeBar,        // 90-day uptime bar chart
+  IncidentTimeline, // Chronological incident updates
+  SystemCard,       // Single system status card with uptime bar
+} from '@alliance-droid/status-feedback-system';
+```
+
+## All Exports
+
+```typescript
+// Components
+import {
+  StatusPage, StatusBanner, FeedbackForm, FeedbackButton,
+  FeedbackBoard, DevFeedback,
+  StatusIndicator, UptimeBar, IncidentTimeline, SystemCard,
+} from '@alliance-droid/status-feedback-system';
+
+// API Client
+import { createStatusClient } from '@alliance-droid/status-feedback-system';
+import type { StatusClient, StatusClientConfig } from '@alliance-droid/status-feedback-system';
+
+// Types
+import type {
+  System, Incident, IncidentUpdate, Feedback, FeedbackResponse,
+  SystemStatus, IncidentStatus, IncidentSeverity, FeedbackStatus,
+  StatusData, IncidentData, UptimeData, BoardData, BoardItem,
+} from '@alliance-droid/status-feedback-system';
+```
+
+## License
+
+Copyright © 2026 Alliance Technical Group. All rights reserved.

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;