@athon-labs/help-widget-react

React help widget. Pass the logged-in user and a URL on your backend. The widget POSTs title, message, reporter fields, and screenshots there. Keep the Athon sk_live_* key on the server.

Install

npm install @athon-labs/help-widget-react

Usage

import { HelpWidget } from '@athon-labs/help-widget-react';

export function AppChrome({ user }: { user: { id: string; email: string; name: string } }) {
  return (
    <HelpWidget
      endpoint="/api/support/report"
      user={{ id: user.id, email: user.email, name: user.name }}
      color="#3d8f78"
      launcher="help"
      position="bottom-right"
      metadata={{ userType: user.role, phone: user.phone, profilePicture: user.avatarUrl }}
    />
  );
}

Props

| Prop | Type | Notes | | --- | --- | --- | | endpoint | string | Your backend URL. Required. | | user | { id, email, name } | Currently logged-in user. Required. | | headers | Record<string, string> | Extra request headers. | | credentials | RequestCredentials | Defaults to include so session cookies are sent. | | defaultTitle | string | Prefills the title field. | | color | string | Brand color for the launcher, header, and send button. Defaults to Athon verdigris. | | launcher | 'help' \\| 'bug' | help shows the word Help. bug shows a bug icon. | | position | 'bottom-right' \\| 'bottom-left' \\| 'top-right' \\| 'top-left' | Corner. Defaults to bottom-right. | | metadata | Record<string, string \\| number \\| boolean \\| null> | Extra key-values stored on the issue (user type, phone, avatar, …). | | onSuccess | (result: unknown) => void | Called with the JSON body from your endpoint. | | onError | (error: Error) => void | Called when capture or submit fails. | | className | string | Added to the launcher root. |

Screenshots

Users can capture the entire screen, the current window/tab, or attach photos. The browser will prompt for screen-share permission. Dismissing the picker is ignored. Images must be PNG, JPEG, WebP, or GIF (max 5).

Backend proxy

The widget does not talk to Athon directly. Your server receives the multipart POST, adds appId (or projectId) and Authorization: Bearer sk_live_…, then forwards to Athon ingest.

ATHON_LIVE_KEY=sk_live_…
ATHON_APP_ID=app_…
ATHON_INGEST_URL=https://YOUR_ATHON_HOST/api/v1/ingest/issues

Next.js

app/api/support/report/route.ts:

export async function POST(request: Request) {
  const form = await request.formData();
  form.set('appId', process.env.ATHON_APP_ID ?? '');

  const upstream = await fetch(process.env.ATHON_INGEST_URL ?? '', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.ATHON_LIVE_KEY}` },
    body: form,
  });

  return new Response(await upstream.text(), {
    status: upstream.status,
    headers: { 'content-type': upstream.headers.get('content-type') ?? 'application/json' },
  });
}

Point <HelpWidget endpoint="/api/support/report" /> at that route.

Node.js

Node 18+. Do not run a JSON body parser on this route.

import { createServer } from 'node:http';

const server = createServer(async (req, res) => {
  if (req.method !== 'POST' || req.url !== '/api/support/report') {
    res.writeHead(404);
    res.end('Not found');
    return;
  }

  const incoming = new Request('http://local/api/support/report', {
    method: 'POST',
    headers: req.headers,
    body: req,
    duplex: 'half',
  });

  const form = await incoming.formData();
  form.set('appId', process.env.ATHON_APP_ID ?? '');

  const upstream = await fetch(process.env.ATHON_INGEST_URL ?? '', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.ATHON_LIVE_KEY}` },
    body: form,
  });

  res.writeHead(upstream.status, {
    'content-type': upstream.headers.get('content-type') ?? 'application/json',
  });
  res.end(await upstream.text());
});

server.listen(3000);

SvelteKit

src/routes/api/support/report/+server.ts:

import { env } from '$env/dynamic/private';
import type { RequestHandler } from './$types';

export const POST: RequestHandler = async ({ request }) => {
  const form = await request.formData();
  form.set('appId', env.ATHON_APP_ID);

  const upstream = await fetch(env.ATHON_INGEST_URL, {
    method: 'POST',
    headers: { Authorization: `Bearer ${env.ATHON_LIVE_KEY}` },
    body: form,
  });

  return new Response(await upstream.text(), {
    status: upstream.status,
    headers: { 'content-type': upstream.headers.get('content-type') ?? 'application/json' },
  });
};

Express, Next.js Pages Router, and Hono examples are in @athon-labs/help-widget-core proxy docs.