@webority/support-react 0.13.0

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) Webority Technologies. All rights reserved.
+
+This software and its source code are proprietary and confidential to
+Webority Technologies. Use is restricted to Webority products and teams under
+internal license. Redistribution outside Webority Technologies is prohibited.

package/README.md

@@ -0,0 +1,120 @@
+# @webority/support-react
+
+Customer support for a React portal: a ticket centre, a report-an-issue button that attaches a
+screenshot of the page, and support contact details. It talks to the Webority Support API that
+the product's backend hosts, and it is built on `@webority/ui-react` and `@webority/theme`, so it
+looks like the rest of the portal with no extra CSS.
+
+## Install
+
+```bash
+npm install @webority/support-react @webority/ui-react react-bootstrap bootstrap@5.3.3
+```
+
+`@webority/ui-react`, `react`, `react-dom`, `react-bootstrap` and `bootstrap` are peer
+dependencies: the portal already has them. Pin `@webority/support-react` to the same exact
+version as `@webority/ui-react`. The screenshot uses `html-to-image`, which installs with the
+package.
+
+## Set up the provider
+
+Give the provider a client built on the portal's own HTTP instance. That instance already
+carries the bearer token and refreshes it, so the support calls sign in the same way as every
+other call. Attachments are fetched through it too, so private files never need a public URL.
+
+```jsx
+import { createSupportClient, SupportProvider } from "@webority/support-react";
+import { userClient } from "./services/api/clients";
+
+const supportClient = createSupportClient(userClient, "/api/support");
+
+export function App() {
+    return (
+        <SupportProvider client={supportClient}>
+            <Routes />
+        </SupportProvider>
+    );
+}
+```
+
+`createSupportClient(http, basePath = "/api/support")` accepts any axios-like instance with
+`get(url, config)` and `post(url, data, config)` that resolve to `{ data }`. Every method
+rejects with a `SupportApiError` carrying `code`, `status` and a `message` written for the
+person, which the components show as-is.
+
+| Method | Request |
+|---|---|
+| `getConfig()` | `GET {base}/config` |
+| `listTickets()` | `GET {base}/tickets` |
+| `getTicket(id)` | `GET {base}/tickets/{id}` |
+| `createTicket({ category, subject, body, pageUrl, userAgent, appVersion, files, screenshots })` | `POST {base}/tickets`, multipart |
+| `reply(id, { body, files, screenshots })` | `POST {base}/tickets/{id}/replies`, multipart |
+| `reopen(id)` | `POST {base}/tickets/{id}/reopen` |
+| `rate(id, { satisfaction, comment })` | `POST {base}/tickets/{id}/rating`, JSON |
+| `fetchAttachment(id)` | `GET {base}/attachments/{id}`, returns a `Blob` |
+
+## Components
+
+### `<SupportCenter />`
+
+The support page: the customer's tickets with status tabs and a search box, one ticket's
+conversation, and a New ticket dialog.
+
+```jsx
+<SupportCenter appVersion={import.meta.env.VITE_APP_VERSION} defaultCategory="Question" />
+```
+
+| Prop | What it does |
+|---|---|
+| `initialTicketId` | Open this ticket first. |
+| `defaultCategory` | Preselected in the New ticket form when the config lists it. |
+| `appVersion` | Recorded on new tickets so support knows which build you were on. |
+
+Support emails link to the support page with `?ticket=<id>`. The centre opens that ticket and
+keeps the parameter in step as tickets open and close, so a refresh stays on the same ticket.
+In a ticket the customer can reply with files (pasting an image into the message attaches it),
+reopen a settled ticket, and say whether it solved their problem. Files are checked against the
+config's type, size and count limits before anything uploads.
+
+### `<ReportIssue />`
+
+A button that takes a screenshot of the current page, then opens a dialog to describe the
+problem. The person can remove the screenshot and add more images by picking, dropping or
+pasting them. The ticket records the page address, the browser and the product version.
+
+```jsx
+<ReportIssue floating appVersion={version} getTicketHref={(id) => `/support?ticket=${id}`} />
+```
+
+| Prop | What it does |
+|---|---|
+| `label` | Button text. Default "Report an issue". |
+| `floating` | Pin the button to the bottom corner of the screen. |
+| `defaultCategory` | Preselected when the config lists it. Default "Bug report". |
+| `appVersion` | Recorded on the ticket. |
+| `getTicketHref(id)` | Shows a View ticket link to the new ticket. |
+| `onOpenTicket(ticket)` | Called by the View ticket button when there is no href. |
+| `onCreated(ticket)` | Called once the ticket is raised. |
+
+The screenshot is taken before the dialog opens, and the button itself is left out of it.
+Anything else the page marks with `data-support-capture="exclude"` is left out too.
+
+### `<SupportContact />`
+
+The support email with a copy button, the phone number as a call link, and the hours, from the
+support config. A field the product has not set is left out, and nothing renders when none is.
+
+```jsx
+<SupportContact />
+```
+
+## Hooks
+
+`useSupportConfig()`, `useSupportTickets()` and `useSupportTicket(id)` return the data with
+`loading`, `error` and `reload`. `useSupportTicket` also returns `reply`, `reopen` and `rate`,
+each resolving to the updated ticket. `useSupportClient()` returns the client itself.
+
+## Display rules
+
+Status text always comes from the API's `statusLabel`. Times show in the viewer's own time zone
+with the zone named.