@blueforge-studio/support-kit

React pieces for apps that send their users to support-os: a "Contact support" button with a ticket dialog, help-center deep links and a ticket status badge. No Tailwind or Radix needed; plain CSS that reads the host's shadcn-style tokens (with fallbacks).

import { SupportButton, HelpLink, TicketStatusBadge } from '@blueforge-studio/support-kit';
import '@blueforge-studio/support-kit/styles.css';

<SupportButton app="taskmaster" />
<HelpLink baseUrl="https://support-app.blueforge.studio" workspace="taskmaster" slug="getting-started">Getting started</HelpLink>
<TicketStatusBadge status="pending" />

Component	What it does
`SupportButton`	Button + modal (focus moves in, Escape closes, focus returns). Posts `{ subject, description, context }` to `endpoint` (default `/api/support/tickets`). `context` = `{ app, route, url, ...your keys }`. Props: `app`, `endpoint`, `context`, `labels` (translate every string), `onSubmitted(ticketId?)`, `className`
`HelpLink` / `helpUrl()`	Anchor to `<baseUrl>/help/<workspace>[/<article>]` (segments encoded). Opens in a new tab
`TicketStatusBadge`	`open` / `pending` / `resolved` / `closed` pill; always shows text. `labels` prop to translate

The key never reaches the browser

SupportButton posts to your app's own route handler. That handler, on the server, adds the API key and the signed-in user, then calls support-os POST /api/v1/tickets. Do not trust context for identity: take the user from your session.

support-os requires the requester: send customer: { email, name? } (or the id of an existing customer as customer_id), otherwise it answers 400. As of service-support 0.1.0 its support-os adapter has no field for that, so until it does, call the REST endpoint directly:

// app/api/support/tickets/route.ts (sketch)
const { subject, description, context } = await req.json();
const user = await requireUser();
const res = await fetch(`${process.env.SUPPORT_OS_API_URL}/api/v1/tickets`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.SUPPORT_OS_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    subject, description,
    customer: { email: user.email, name: user.name },
    metadata: { ...pick(context, ['app', 'route', 'url']), forge_user_id: user.id }, // flat string map, max 20 keys
  }),
});
return Response.json({ data: { id: (await res.json()).data?.id } }, { status: res.ok ? 200 : 502 });

If the session is a Bearer token or the route is on another origin, pass headers={{ Authorization: … }} and/or credentials="include" to SupportButton. Apps whose users are not forge users send their own id (e.g. app_user_id) instead of forge_user_id; "my tickets" then filters by customer_email.

Metadata becomes the "Context" panel in the support-os thread, and forge_user_id powers "my tickets" (GET /api/v1/tickets?forge_user_id=). Spec: support-os docs/plans/2026-10-15-fleet-integration-spec.md §4.3.

Theming

styles.css uses --primary, --primary-foreground, --card, --card-foreground, --border, --input, --background, --muted, --muted-foreground, --destructive, --ring, --info, --warning, --success, each with a fallback, so it works unthemed and follows a shadcn theme (light and dark) when one is present. Classes are prefixed sk-.

Not included

A "my tickets" list component (needs a decision on where the list is shown), and any server code: tickets are created with service-support.

Versión	Firma	SBOM	Att
0.1.2
0.1.1
0.1.0

@blueforge-studio/support-kit

Información del paquete

Versiones

Cadena de suministro por versión

Cadena de suministro

Dependencias

README

@blueforge-studio/support-kit

The key never reaches the browser

Theming

Not included

Versión	Publicada
0.1.2	2026-10-15
0.1.1	2026-10-15
0.1.0	2026-10-15