@supportwire/messenger-js-sdk 1.0.26

package/README.md

@@ -0,0 +1,80 @@
+# @supportwire/messenger-js-sdk
+
+Drop-in replacement for [`@intercom/messenger-js-sdk`](https://www.npmjs.com/package/@intercom/messenger-js-sdk) that mounts a SupportWire widget.
+
+Native usage:
+
+```js
+import SupportWire from '@supportwire/messenger-js-sdk';
+
+SupportWire({
+  app_id: 'your-supportwire-widget-slug',
+  user_id: currentUser.id,
+  email: currentUser.email,
+  user_hash: currentUser.supportwireHash,
+  name: currentUser.name,
+});
+```
+
+If you're migrating an existing Intercom integration, default imports can be
+renamed at the import site — no other code change required:
+
+```diff
+- import Intercom from '@intercom/messenger-js-sdk';
++ import Intercom from '@supportwire/messenger-js-sdk';
+
+  Intercom({
+-   app_id: 'your-intercom-app-id',
++   app_id: 'your-supportwire-widget-slug',
+    user_id: currentUser.id,
+    email: currentUser.email,
+-   user_hash: currentUser.intercomHash,
++   user_hash: currentUser.supportwireHash,
+    name: currentUser.name,
+  });
+```
+
+## What's the `app_id`?
+
+For SupportWire, `app_id` is your **widget slug** — the opaque, lowercase
+alphanumeric identifier shown next to each widget in the admin panel at
+`/settings/widgets`. Each widget is owned by one organization. Your
+backend resolves the org from the widget slug; you do not need to send a
+separate org identifier.
+
+## Identity & HMAC
+
+When identity verification is enabled on your organization, send a
+`user_hash` computed server-side. The HMAC subject is
+`user_id ?? email` — i.e. when `user_id` is present it wins, otherwise
+the (lowercased, trimmed) email is signed.
+
+```js
+import crypto from 'node:crypto';
+const subject = currentUser.id ?? currentUser.email.trim().toLowerCase();
+const userHash = crypto
+  .createHmac('sha256', SUPPORTWIRE_HMAC_SECRET)
+  .update(subject)
+  .digest('hex');
+```
+
+## Supported methods
+
+| Method | Status |
+|---|---|
+| `Intercom(settings)` / `boot(settings)` | ✅ |
+| `update(settings)` | ✅ |
+| `shutdown()` | ✅ |
+| `show()` / `hide()` | ✅ |
+| `showNewMessage(content?)` | ✅ (opens widget + sends content if supplied) |
+| `onShow(cb)` / `onHide(cb)` / `onUnreadCountChange(cb)` / `onUserEmailSupplied(cb)` | ✅ |
+| `getVisitorId()` / `whoami()` | ⚠️ returns `null` for now |
+| `trackEvent(name, metadata?)` | ⚠️ no-op + warn until backend endpoint ships |
+| `hideNotifications(hidden)` | ⚠️ no-op + warn |
+| `startTour` / `showArticle` / `showNews` / `startSurvey` / `startChecklist` / `showTicket` / `showConversation` / `showSpace` / `showMessages` | ⚠️ no-op + warn (no SupportWire equivalent) |
+
+## Differences from Intercom
+
+- The product surface is smaller (no tours/articles/news/surveys). Those methods are silent no-ops so existing call sites don't throw.
+- `getVisitorId()` is synchronous in Intercom; ours returns `null` until an async fallback is added.
+- We do not masquerade as `window.Intercom` globally — the queue stub lives on `window.SupportWireMessenger` so both packages can coexist during migration.