https://github.com/thunderbird/thundermail-zendesk-sidebar
Private Zendesk Support sidebar for viewing Thundermail customer account context.
https://github.com/thunderbird/thundermail-zendesk-sidebar
Last synced: 24 days ago
JSON representation
Private Zendesk Support sidebar for viewing Thundermail customer account context.
- Host: GitHub
- URL: https://github.com/thunderbird/thundermail-zendesk-sidebar
- Owner: thunderbird
- License: mpl-2.0
- Created: 2026-06-24T10:58:51.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-25T21:05:20.000Z (about 1 month ago)
- Last Synced: 2026-07-09T13:28:34.475Z (30 days ago)
- Size: 178 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Thundermail Zendesk Sidebar
The Thundermail Zendesk Sidebar helps support agents give better, faster answers to people using
Thunderbird services. When an agent opens a Zendesk ticket, the sidebar shows the Thundermail account
context connected to the requester: subscription state, account details, mail setup, legal acceptance,
and links to the internal records that may help resolve the issue.
This is a private Zendesk Support app. Agents sign in with their Thunderbird Account, and the
accounts API only returns data to active staff users with the required support-view permissions.
The app is built as a standalone Vite, Vue, and TypeScript package so it can stay close to the rest of
the Thundermail frontend stack while still producing the zip file Zendesk expects.
## Development
### Local Testbed
Create a local `.env` from `.env.example` to control the Zendesk app settings for local development.
Run the development server with the following command and open the URL it tells you. At the root
there is a local testbed that loads the sidebar.
```bash
npm install
npm run dev
```
There are three ways to test the sidebar:
* Testbed Local: Uses local mocks to simulate the sidebar loading data from a server.
* Testbed Stage: Uses real OAuth and makes a request to the configured stage server.
* Zendesk Apps: Follow Zendesk's instructions to [test your app locally](https://developer.zendesk.com/documentation/apps/getting-started/using-zcli/#testing-your-zendesk-app-locally).
Note that you may run into local network access or CORS issues if you use localhost for either
Testbed Stage or the Zendesk Apps approach. You may need to set up a tunneling mechanism such as
Tailscale Funnel.
### Useful checks
Run these checks before you push a pull request
```bash
npm run test
npm run typecheck
npm run lint
```
## Deployment
### Zendesk
Create a Zendesk upload archive with:
```bash
npm run build
```
The build produces only the production ZAF entry points from `src/zaf`, and then
creates `dist/zendesk-sidebar.zip`. Upload `dist/zendesk-sidebar.zip` as a private Support app in
Zendesk Admin Center, or use the update functionality for the existing application.
The private app needs some settings when it is installed in Zendesk. You can see example values in
the `.env.example` file. Once installed you can get the Zendesk Application ID to adjust the Keycloak
settings. Use production hosts and client id for the production install.
More information on how to upload/update Zendesk apps is [available in their
documentation](https://developer.zendesk.com/documentation/apps/getting-started/using-zcli/#updating-a-private-zendesk-app).
### Keycloak
The Keycloak client should be public and use the standard authorization-code flow with PKCE. Add the
packaged callback page as an exact valid redirect URI, and add the Zendesk app origin as a web origin
so the adapter can exchange and refresh tokens from inside Zendesk.
Do not use the development URLs in production clients.
* Redirect URL:
* Stage/Production: `https://YOUR_APP_ID.apps.zdusercontent.com/YOUR_APP_ID/assets/*/oauth-callback.html`
* For Development: `http://localhost:5175/assets/oauth-callback.html`
* Web Origin
* Stage/Production: `https://YOUR_APP_ID.apps.zdusercontent.com`
* For Development: `http://localhost:5175`
* Client Authentication: Off
* PCKE Method: S256
* Client scopes: Delete all optional scopes, especially offline_access
* Advanced Settings: Reduce access token lifespan, client session idle/max to a minimum