@zuperscore/support-help-sdk

Embeddable React widget that lets any application (currently the Conduct frontend) chat with the Zuperscore Support team in real time.

How it works

+-----------------+      +-------------+       +-------------------+
| Conduct         |  1.  |             |  2.   |                   |
| Frontend        +----->+ support-api +------>+ Conduct backend   |
| (embeds widget) |      | /v1/support-|       | /api/users/me     |
+-----------------+      | help/auth   |       +-------------------+
      ^   |              +------+------+                |
      |   |                     |                       |
      |   |              3. 4h JWT                      |
      |   v                     v                       |
      |   +------ Socket.IO /support-help (namespace) --+
      |                         |
      |                 4. support:message ⇄ agent UI (WA chats)
      |
      +-- receives replies from support agents in real time

1. The widget is mounted inside the Conduct frontend and given a callback that returns the current Conduct access token.
2. On open, it calls POST /v1/support-help/auth on support-api with that access token. The API forwards it to the Conduct backend /api/users/me endpoint to verify the user.
3. If the user is valid, support-api mints a short-lived JWT (default 4 hours, claim type: "support_help"). The widget uses this JWT to open a Socket.IO connection on the /support-help namespace.
4. User messages are persisted in the same WhatsApp chat tables used by the Support team, under a pseudo phone conduct-<conductUserId>. This means agents see and reply from the existing Support chat UI — no separate inbox. Their replies are mirrored to the widget instantly.

The JWT expires after 4 hours; the SDK refreshes it automatically using the getConductAccessToken callback.

Install

This package is not published yet. Consume it via a workspace or tarball:

# from Conduct frontend repo
yarn add @zuperscore/support-help-sdk@file:../support-help-sdk

Usage

import { SupportHelpWidget } from "@zuperscore/support-help-sdk";

export function RootLayout({ children }) {
  return (
    <>
      {children}
      <SupportHelpWidget
        apiBaseUrl={process.env.NEXT_PUBLIC_SUPPORT_API_URL!}
        getConductAccessToken={async () => {
          // Return the current Conduct JWT access token.
          // This is called on mount and whenever the support-help token
          // needs to be refreshed (every ~4h).
          return localStorage.getItem("conductAccessToken") || "";
        }}
      />
    </>
  );
}

Headless / custom UI

If you want your own UI, use the useSupportHelp hook or the lower-level clients:

import { useSupportHelp } from "@zuperscore/support-help-sdk";

const { status, messages, sendMessage } = useSupportHelp({
  apiBaseUrl,
  getConductAccessToken
});

import {
  SupportHelpApiClient,
  SupportHelpSocketClient
} from "@zuperscore/support-help-sdk";

const api = new SupportHelpApiClient({ apiBaseUrl, getConductAccessToken });
const auth = await api.authenticate();
const sock = new SupportHelpSocketClient(apiBaseUrl, auth.token, auth.chat.id);
sock.connect();
sock.on("message", (m) => console.log(m));

Server-side requirements (support-api)

The following env vars must be set on support-api for the widget to work:

| Variable | Purpose | |---------------------------------|----------------------------------------------------------------------------| | SUPPORT_HELP_CONDUCT_BASE_URL | Conduct backend base URL. Defaults to production. | | SUPPORT_HELP_CONDUCT_ME_PATH | Path that returns the current user from a Conduct access token. | | SUPPORT_HELP_JWT_SECRET | Secret used to sign the 4h support-help JWT. Falls back to JWT_SECRET. | | SUPPORT_HELP_JWT_EXPIRY_HOURS | Lifetime of the support-help JWT. Default 4. | | SUPPORT_HELP_PHONE_NUMBER_ID | wa_channels.phone_number_id of the channel that backs the widget chats. | | SUPPORT_HELP_ORG_ID | org_id of the support workspace. |

Socket namespace: /support-help on path /ws (same HTTP server as the rest of the WhatsApp socket work). Events:

| Event | Direction | Payload | |------------------------|-----------------|------------------------------------------------| | support:chat:join | client → server | { chatId } | | support:chat:leave | client → server | { chatId } | | support:message:send | client → server | { text?, mediaUrl?, mediaType? } (with ack) | | support:message | server → client | Full wa_messages row (inbound + outbound) |

Build

yarn install
yarn build

Publishing

This package publishes to the public npm registry as @zuperscore/support-help-sdk (scoped with publishConfig.access=public).

One-time setup

npm login                      # log in with an account that has publish rights on the @zuperscore org
npm whoami                     # verify

Cut a release

cd support-help-sdk

# 1. bump version (creates a git commit + git tag v0.1.1)
npm run release:patch          # or release:minor / release:major

# 2. dry-run first to inspect what will be uploaded
npm run publish:dry

# 3. publish (runs clean + typecheck + build via prepublishOnly,
#             verifies version isn't already on the registry,
#             requires a clean git tree and an npm login)
npm run publish:latest

# Pre-release (published under the "next" dist-tag)
npm run publish:next

# Finally, push the tag created by npm version
git push && git push --tags

The publish flow is implemented in scripts/publish.sh.

support-chat-sdk

support-chat-sdk