@inferenc/sdk 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 0.3.0 — first npm release
+
+- `update({ name, email, phone, attributes, company, page })` pushes contact data from the browser (debounced 500 ms, coalesced, queued for anonymous visitors until identified).
+- `upsertContact()` and `upsertCompany()` in `@inferenc/sdk/server`.
+- New `POST /v1/public/chat/contacts` route (signed `Widget` token). Unsigned name/email/phone are stored as `unverified_*`; attributes merge into `custom_attributes`; company is stored on the contact as `company_profile`.
+- Inbox contact panel and contact detail show attributes, company, unverified fields and the last seen page.
+- `showNewMessage(prefill?)`, `showMessages()`, `onShow()`, `onHide()` and `onUnreadCountChange()`; `getState()` includes `unreadCount`. The launcher shows an unread badge.
+- The widget opens on a Messenger-style home with the conversation list for identified users.
+- Requires the matching API and hosted widget deployment.
+
+## 0.2.0
+
+- `hideDefaultLauncher` init option hides the launcher bubble from first paint; open the panel with `show()`.
+- `update({ hideDefaultLauncher })` changes widget behaviour at runtime (for example while a cookie banner is visible).
+- `widgetOrigin` and `apiOrigin` init options for staging and local development (https, or http for localhost only).
+- `normalizeEventName()` exported from `@inferenc/sdk` and `@inferenc/sdk/server` to map legacy free-form event names to valid snake_case names.
+- `getState()` now includes `launcherVisible`.
+- Requires the matching hosted widget; `update()` rejects with a clear error against an older runtime.
+
+## 0.1.0 — release candidate (never published)
+
+- Browser initialization, automatic widget loading, and identity lifecycle methods.
+- Cancellation protection for logout during initialization and account switching.
+- Node-only signing helper compatible with the deployed Inferenc identity API.
+- TypeScript declarations, React/Node examples, and integration/publishing guides.
+- Zero runtime dependencies; ESM package with separate browser and server exports.
+
+- Verified identify handshake automatically creates a contact by workspace and user ID.
+- Browser and Node event tracking with bounded metadata, stable retry IDs, and logout cancellation.
+- Updated Reepl migration examples for frontend and server events.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Inferenc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,190 @@
-# Temporary Holding Version
+# Inferenc SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Support chat for your website and app. Identify signed-in users automatically, let your team reply, and restore conversations when users return—without asking visitors to fill in their name or email.
+
+## Install
+
+```sh
+npm install @inferenc/sdk
+```
+
+ES modules; Node.js 20+ for the server helper. Modern browsers and bundlers for the browser entry. TypeScript declarations are included. There are no runtime dependencies and no consumer build/install scripts.
+
+## Browser: anonymous visitors
+
+```js
+import inferenc from '@inferenc/sdk';
+
+await inferenc.init({ embedHash: 'YOUR_WIDGET_EMBED_HASH' });
+await inferenc.show();
+```
+
+Get an embed hash from your Inferenc widget configuration and allow your website's domain. Use one widget per page. Remove any existing `widget-loader.js` script before switching to the package; the SDK loads it for you.
+
+## Browser: signed-in users
+
+```js
+import inferenc from '@inferenc/sdk';
+
+await inferenc.init({
+  embedHash: 'YOUR_WIDGET_EMBED_HASH',
+  getIdentityToken: async () => {
+    const response = await fetch('/api/support/identity', {
+      credentials: 'same-origin',
+      cache: 'no-store',
+    });
+    if (!response.ok) throw new Error('Unable to authenticate support chat');
+    return (await response.json()).token;
+  },
+});
+
+// Your Help / Contact us action:
+await inferenc.show();
+
+// Before clearing the app's authenticated session:
+inferenc.shutdown();
+```
+
+The callback is invoked again before token expiry. It must fetch a fresh token from your authenticated server; do not repeatedly return a cached token. A one-off `identityToken` is also supported, but you must replace it before expiry. Do not supply both options.
+
+On login/account switch, call `await inferenc.identify({ getIdentityToken })`. On normal route changes, keep the widget running. On logout, call `shutdown()` synchronously before clearing auth or rendering another user.
+
+## Server: sign identity from your authenticated session
+
+```js
+import { signWidgetIdentity } from '@inferenc/sdk/server';
+
+// Inside your existing authenticated backend handler:
+const token = signWidgetIdentity({
+  secret: process.env.INFERENC_IDENTITY_SECRET,
+  embedHash: process.env.INFERENC_EMBED_HASH,
+  userId: authenticatedUser.id,
+  name: authenticatedUser.name || undefined,
+  email: authenticatedUser.email || undefined,
+});
+
+// Return { token } with Cache-Control: no-store.
+```
+
+The signing key must be provisioned for this specific widget by your Inferenc administrator. It is different from the public embed hash and is never included in the browser. Name/email are optional; the immutable `userId` links history across sessions and devices. Never take the signed user ID from an untrusted request body/query parameter. See [server integration](./docs/SERVER.md).
+
+## API
+
+| Method | Behavior |
+| --- | --- |
+| `init({ embedHash, ...identity })` | Loads the hosted runtime once and boots the widget. Returns a promise. |
+| `boot(identity?)` | Reboots an initialized widget; anonymous boot preserves an existing anonymous session. |
+| `identify(identity)` | Changes the signed-in user or identity provider. |
+| `trackEvent(name, metadata?, options?)` | Records an event for the verified user; returns an event/contact receipt. |
+| `shutdown()` | Clears the active identity and local session synchronously; returns to anonymous state. |
+| `show()` | Opens the panel; await initialization first. |
+| `hide()` | Closes the panel; does not remove the launcher or stop the runtime. |
+| `update({ hideDefaultLauncher, name, email, phone, attributes, company, page })` | Changes widget behaviour at runtime and pushes contact data; applied once the runtime is ready. See [Contact data](#contact-data-attributes-and-companies). |
+| `showNewMessage(prefill?)` | Opens the panel on a new conversation, optionally prefilling the composer (string, up to 2000 characters). |
+| `showMessages()` | Opens the panel on the conversation list (identified users). |
+| `onShow(cb)` / `onHide(cb)` | Called when the panel opens or closes. Return an unsubscribe function. DOM events `inferenc:show` and `inferenc:hide` are also dispatched. |
+| `onUnreadCountChange(cb)` | Called with the new unread count when it changes (the launcher also shows a badge). Returns an unsubscribe function. |
+| `normalizeEventName(name)` | Maps free-form names to valid snake_case event names (also exported from `/server`). |
+| `getState()` | Returns `{ status, identified, isOpen, launcherVisible, unreadCount }`. Safe during SSR. |
+
+`init`, `boot`, `identify`, `show`, and `hide` return promises. Handle errors, including `AbortError` when an operation is superseded by logout or another identity operation. `loadTimeoutMs` on `init` defaults to 20 seconds. After a script load failure, reload the page to retry; the SDK deliberately avoids injecting duplicate runtimes.
+
+`init()` completion means the runtime has booted, not that remote history has finished loading. `identified: true` means the backend verified the token and created or resolved the contact, even when the user has never opened chat and has no name/email. Neither is an authorization signal for your application. Inferenc validates signed identity on its backend for every protected conversation request.
+
+For failures during later refreshes:
+
+```js
+window.addEventListener('inferenc:identity-error', () => {
+  // Show your app's error UI with a sign-in/reload action.
+});
+```
+
+Do not silently fall back to anonymous chat after a signed-in user's identity fails. Tokens stay in widget memory. Anonymous history is browser-local; verified history is restored from the server. Anonymous sessions are not automatically merged into accounts.
+
+## React, Next.js and Reepl
+
+- [React lifecycle example](./examples/react/SupportChat.tsx)
+- [Server integration and token contract](./docs/SERVER.md)
+- [Reepl migration from Intercom](./docs/REEPL.md)
+- [Publishing and release handoff](./docs/PUBLISHING.md)
+
+Importing the browser entry during SSR is safe; call `init()` only on the client. The `/server` entry is Node-only and blocked for browser-conditioned package resolution. Do not import it into a client component.
+
+## Limits
+
+This is the JavaScript SDK for Inferenc's existing hosted widget and API. It does not bundle or self-host the messenger UI. The hosted runtime can receive updates independently of the npm version. There is no CommonJS entry, React provider package, native mobile SDK, or Intercom history importer in this release. Current notification emails go to the support team, not visitors. `hide()` does not hide the launcher; use the `hideDefaultLauncher` init option or `update()` for a Help-menu-only setup. `widgetOrigin` and `apiOrigin` init options target staging or local servers.
+
+## Development
+
+```sh
+npm ci
+npm test
+npm run check
+npm pack
+```
+
+`npm pack` runs tests and declaration checks, then produces `inferenc-sdk-<version>.tgz`. Only the explicit package allowlist is shipped; tests and development dependencies are excluded.
+
+## Contact data, attributes and companies
+
+Push contact data from the browser or your server and see it in the inbox contact panel and the contact detail page.
+
+```js
+// Browser: debounced 500 ms and coalesced. Anonymous visitors queue until identify().
+await inferenc.update({
+  phone: '+14155550123',
+  attributes: { plan: 'pro', seats: 5, trial: false, legacy_flag: null }, // null deletes a key
+  company: { company_id: 'acme', name: 'Acme Inc', attributes: { tier: 'gold' } },
+  page: { url: location.href, title: document.title, referrer: document.referrer, utm_source: 'google' },
+});
+```
+
+```js
+// Server: name and email are covered by your signing secret and stored as verified.
+import { upsertContact, upsertCompany } from '@inferenc/sdk/server';
+await upsertContact({ secret, embedHash, userId, email, name, attributes: { plan: 'pro' } });
+await upsertCompany({ secret, embedHash, userId, company: { company_id: 'acme', name: 'Acme Inc' } });
+```
+
+Rules (enforced identically in the SDK and the API):
+
+- `attributes` is a flat map of strings (at most 1000 characters), finite numbers, booleans or `null`; keys match `/^[a-z][a-z0-9_]{0,63}$/`; at most 100 keys per call and 100 per contact. Values merge into the contact; `null` deletes a key.
+- Browser `name`, `email` and `phone` are self-reported and stored as `unverified_*` unless they equal the signed token's claims. Server calls sign `name` and `email`, so those are verified.
+- `company.company_id` is required (at most 128 characters). A new `company_id` replaces the contact's company; the same ID merges attributes. The company is stored on the contact (`company_profile`, with the display name also copied to `company`). A separate companies table is not created yet.
+- `page` records `last_seen_page` and `last_seen_at`; `url` and `referrer` must be http(s).
+- Calls are idempotent. Queued anonymous data is discarded by `shutdown()`.
+- Needs the matching API (`POST /v1/public/chat/contacts`) and hosted widget.
+
+## Contact creation and custom events
+
+Awaiting signed-in `init()` or `identify()` now waits for `POST /v1/public/chat/identify`. It verifies the token and creates/resolves the user contact immediately; opening chat, sending a message, name and email are unnecessary. Identity failures reject and leave the widget in error state. This requires the matching hosted widget and API deployment.
+
+After identification, record browser activity:
+
+```js
+await inferenc.trackEvent('report.exported', { format: 'pdf', pages: 12 });
+```
+
+For business activity in an authenticated backend handler or job:
+
+```js
+import { trackEvent } from '@inferenc/sdk/server';
+
+await trackEvent({
+  secret: process.env.INFERENC_IDENTITY_SECRET,
+  embedHash: process.env.INFERENC_EMBED_HASH,
+  userId: authenticatedUser.id,
+  name: 'subscription.activated',
+  metadata: { plan: 'pro', seats: 3 },
+  eventId: 'subscription_abc_activated', // persist this with the job/outbox
+  createdAt: '2026-10-19T10:00:00.000Z', // persist original occurrence time
+});
+```
+
+The server helper derives a short-lived signed identity and calls the production API; it also creates/resolves the contact when there has been no browser visit. Optional `email` and `userName` are signed profile fields. Derive `userId` from your authenticated session or trusted job record, never a client-selected ID.
+
+Both methods return `{ event_id, contact_id, duplicate }`. Event names start with a letter and contain up to 100 letters, digits, underscores, dots or hyphens. Metadata is a flat JSON primitive map (string, finite number, boolean or null), at most 50 keys and 16KB UTF-8. `eventId` allows 1–128 letters, digits, underscores or hyphens. `createdAt` is an optional UTC ISO timestamp, no more than five minutes in the future.
+
+Without `eventId`, each call generates a new UUID. Transient network, 429 and 5xx failures retry up to twice with the same payload and ID. For job retries or retries across page reloads, persist and reuse the ID and original payload (including `createdAt` if supplied). The same ID with changed content returns 409; do not retry that conflict as a new ID. Logout/account changes abort in-flight browser requests and prevent retries under another account. An already accepted event cannot be undone by aborting the browser request.
+
+Events are contextual customer activity, not authoritative billing proofs: browser and server events currently share the `sdk` source and signed-user authentication. Never send secrets or payment credentials in metadata.

package/docs/PUBLISHING.md

@@ -0,0 +1,97 @@
+# SDK handoff and publishing checklist
+
+## Current status
+
+`@inferenc/sdk` is published to npm under the `@inferenc` organization, starting with `0.3.0` (`0.1.0` and `0.2.0` were never published). The source lives in the private monorepo at `packages/sdk`; no public GitHub repository exists yet. Later releases follow the npm steps below with the new version number in place of `0.1.0`.
+
+The proposed public repository is `inferenc/inferenc-sdk`. The proposed npm scope is `@inferenc`; scope ownership still needs confirmation. GitHub organization access does not grant npm scope access.
+
+## Use the package before publication
+
+From this directory:
+
+```sh
+npm ci
+npm test
+npm run check
+npm pack
+```
+
+This produces `inferenc-sdk-0.1.0.tgz`. In a consumer project:
+
+```sh
+npm install /absolute/path/to/inferenc-sdk-0.1.0.tgz
+```
+
+The import paths are already the final ones:
+
+```js
+import inferenc from '@inferenc/sdk';
+import { signWidgetIdentity } from '@inferenc/sdk/server'; // server files only
+```
+
+Only the browser entry belongs in a client bundle. This is a zero-runtime-dependency ESM package, with no preparation/build hook required on consumer install.
+
+## Publish source to GitHub, when ready
+
+Publish **only this directory**. Do not push the parent product workspace or copy its operational files, environment files, customer IDs, signing-key registry scripts, or credentials into the SDK repository.
+
+Review `LICENSE` (MIT), package contents, and examples. Initialize a separate repository and create the public GitHub repo only when authorized to proceed:
+
+```sh
+git init -b main
+git add .gitignore .github package.json package-lock.json tsconfig.json src test README.md LICENSE CHANGELOG.md docs examples
+git commit -m "feat: prepare Inferenc browser and server SDK"
+gh repo create inferenc/inferenc-sdk --public --source=. --remote=origin --push
+```
+
+If that repository already exists, inspect it and connect its remote instead of recreating or overwriting it. There are no automated publish workflows in this package. The included workflow runs tests, type checks and pack checks on Node 20, 22 and 24; it has not run on GitHub yet.
+
+After the repo exists, add its metadata:
+
+```sh
+npm pkg set repository.type=git repository.url=git+https://github.com/inferenc/inferenc-sdk.git
+npm pkg set homepage=https://github.com/inferenc/inferenc-sdk#readme
+npm pkg set bugs.url=https://github.com/inferenc/inferenc-sdk/issues
+```
+
+## First npm publication
+
+1. Log in with the intended maintainer account using `npm login`; confirm with `npm whoami`.
+2. Confirm the account can publish under the npm organization `@inferenc`. Create/obtain that scope or agree on another package name before proceeding. A 404 for the package name does not establish ownership of its scope.
+3. Update the release status in README and CHANGELOG when publication is actually occurring. Confirm the license and repository metadata.
+4. Run the checks and inspect the exact tarball:
+
+```sh
+npm ci
+npm test
+npm run check
+npm pack
+# Inspect the allowlisted files; no secrets, private material or node_modules.
+tar -tzf inferenc-sdk-0.1.0.tgz
+```
+
+5. Publish the reviewed artifact explicitly as public:
+
+```sh
+npm publish ./inferenc-sdk-0.1.0.tgz --access public
+```
+
+Complete npm's login/2FA prompts yourself. Do not put credentials in chat, source files, examples, or shell history. Organization-scoped packages need explicit public access for public distribution: [npm's organization package guide](https://docs.npmjs.com/creating-and-publishing-an-organization-scoped-package/).
+
+6. Verify registry availability and installation from a clean project:
+
+```sh
+npm view @inferenc/sdk@0.1.0 version dist.integrity
+npm install @inferenc/sdk@0.1.0
+node --input-type=module -e "import sdk from '@inferenc/sdk'; console.log(typeof sdk.init)"
+node --input-type=module -e "import { signWidgetIdentity } from '@inferenc/sdk/server'; console.log(typeof signWidgetIdentity)"
+```
+
+7. Commit final release metadata, tag `v0.1.0`, and create the GitHub release with the same artifact. Do not claim a registry install works until step 6 succeeds. If publishing fails, keep the documented status as unpublished.
+
+npm versions cannot be overwritten. Fix a published package with a new version rather than rebuilding and reusing an existing version. For later automated releases, consider npm trusted publishing with GitHub OIDC after the public repo/package exist; it is not configured here. [Official trusted publishing documentation](https://docs.npmjs.com/trusted-publishers/).
+
+## What the SDK does not provision
+
+Customers still need an Inferenc widget, an allowed website domain, and a widget-specific server signing key. The package does not create accounts, expose an anonymous identity-signing service, install a shared signing secret, or change notification settings. The main product/backend stays private.

package/docs/REEPL.md

@@ -0,0 +1,152 @@
+# Reepl: migrate the current Intercom integration
+
+This is an implementation guide, not a statement that Reepl has already migrated. Install with `npm install @inferenc/sdk`.
+
+## Backend: keep the existing authenticated profile route
+
+In `reepl-backend/lambdas/viewOrUpdateProfile/index.mjs`, install the SDK in the Lambda's package and import:
+
+```js
+import { signWidgetIdentity } from '@inferenc/sdk/server';
+```
+
+The existing handler derives `userID` and `email` from `event.requestContext.authorizer.claims`. Keep that authorization. Inside its successful GET-profile branch, after `filteredResult` is available and before returning the normal profile, add an opt-in identity response:
+
+```js
+if (event.queryStringParameters?.support_identity === '1') {
+  if (!process.env.INFERENC_IDENTITY_SECRET || !process.env.INFERENC_EMBED_HASH) {
+    const response = generateResponse(503, { message: 'Support chat is unavailable' });
+    response.headers = { ...response.headers, 'Cache-Control': 'no-store' };
+    return response;
+  }
+  const token = signWidgetIdentity({
+    secret: process.env.INFERENC_IDENTITY_SECRET,
+    embedHash: process.env.INFERENC_EMBED_HASH,
+    userId: userID,
+    name: filteredResult.name || undefined,
+    email: email || undefined,
+  });
+  const response = generateResponse(200, { token, user_id: userID });
+  response.headers = {
+    ...response.headers,
+    'Content-Type': 'application/json',
+    'Cache-Control': 'no-store, private',
+  };
+  return response;
+}
+```
+
+Use the provisioned widget secret, not the existing Intercom secret. Package the SDK dependency with the Lambda or bundle the helper; declaring the dependency alone is insufficient. Keep normal profile responses unchanged. Disable API Gateway caching for this response. Keep the token out of Reepl's persisted profile query cache by requesting this branch directly.
+
+## Frontend: replace the script-loader/provider code with the package
+
+The package replaces the custom `loadInferenc()` helper and global `window.Inferenc` types described in earlier integration notes. Do not use both loaders.
+
+```ts
+import inferenc from '@inferenc/sdk';
+import { apiFetch } from '@/lib/fetcher';
+import useUserStore from '@/store/user-store';
+
+export async function connectSupport(expectedUserId: string) {
+  await inferenc.init({
+    embedHash: process.env.NEXT_PUBLIC_INFERENC_EMBED_HASH!,
+    getIdentityToken: async () => {
+      if (useUserStore.getState().userId !== expectedUserId) throw new Error('Account changed');
+      const result = await apiFetch('/account/profile?support_identity=1', {
+        method: 'GET', cache: 'no-store', skipWorkspaceId: true,
+      });
+      if (useUserStore.getState().userId !== expectedUserId || result.user_id !== expectedUserId) {
+        throw new Error('Account changed');
+      }
+      return result.token;
+    },
+  });
+}
+```
+
+Mount one provider in the existing `IntercomProvider` position in `src/app/[locale]/layout.tsx`. Connect only when authenticated `userId` is available. Reconnect on account change; call `shutdown()` before clearing or switching the current account. Do not run initialization on every pathname or profile refetch. Keep the provider stable across normal navigation. Handle initial connection errors and the `inferenc:identity-error` event in the existing toast UI. Do not use a stale cached `intercom_jwt` or profile response as the new token.
+
+## Help links and logout
+
+Replace `window.Intercom('show')` with `void inferenc.show().catch(...)` in:
+
+- `components/global/sidebar/nav-help.tsx`
+- `components/global/sidebar/nav-user.tsx`
+- `components/global/page-top-bar.tsx`
+- `components/settings/integrations/integrations.tsx`
+- `components/settings/plans/billing.tsx`
+- `components/settings/plans/cancellation-flow-dialog-global.tsx`
+
+In `hooks/auth/use-logout.tsx`, replace Intercom shutdown with `inferenc.shutdown()` **before** clearing auth. Preserve Reepl's existing copilot flush, persisted-cache clearing, desktop logout, and navigation order. Update its tests accordingly.
+
+To preserve the current Help-menu-only experience, pass `hideDefaultLauncher: true` to `inferenc.init(...)`. The launcher bubble is hidden from first paint and `inferenc.show()` still opens the panel. `hide()` only closes the panel; it does not hide the launcher or stop network activity.
+
+For the cookie consent banner in `components/global/cookie-consent-banner.tsx`, replace the old Intercom launcher calls with `inferenc.update({ hideDefaultLauncher: true })` or `inferenc.update({ hideDefaultLauncher: false })` as the banner appears and is dismissed, without changing consent behavior. `update()` called before the runtime is ready is applied once it loads.
+
+## Configuration and scope
+
+Set `NEXT_PUBLIC_INFERENC_EMBED_HASH` on the frontend; set the embed hash and signing secret on the backend. Use the existing provisioned Reepl widget rather than creating a duplicate workspace. Get its IDs/secret from the project owner—this public package contains no customer credentials.
+
+Add `reepl.app` and `app.reepl.io` to the widget allowlist (the app's configured production hosts). Preserve other intentionally allowed hosts. Add preview domains deliberately. The stable user ID is the Cognito subject, so support history follows the person across Reepl workspace switches; it is not a shared workspace conversation.
+
+Migrate frontend and backend Intercom event calls using the event adapter guidance below; replacing the messenger alone does not remove these jobs.
+
+## Acceptance
+
+Verify no contact form, visitor messages, live team replies, close/reopen, page reload, logout/login, second-browser restoration, isolation between two accounts, token refresh after ten minutes, and late identity-request cancellation during logout. Test Help in billing and cancellation flows, and make sure only one widget loads. Run Reepl's type-check, provider/logout tests, backend auth tests, and required deployment builds.
+
+Desktop/webview compatibility needs its own origin and iframe tests. This package does not migrate old Intercom history or add visitor reply emails.
+
+## Replace Intercom event tracking
+
+Wrap legacy Intercom names with `normalizeEventName()` (exported from `@inferenc/sdk` and `@inferenc/sdk/server`), for example `'Upgrade Button - Click'` becomes `'upgrade_button_click'` and `'credits expired'` becomes `'credits_expired'`; it throws `TypeError` when no usable characters remain. Use `inferenc.trackEvent(name, metadata, { eventId, createdAt })` in `services/tracking/intercom.ts` after the support provider's identified initialization completes. Rename the adapter to Inferenc and update its imports/callers. Keep tracking failures from blocking the underlying user action; report failures to existing diagnostics. Anonymous events are rejected. Keep consent rules intact.
+
+```ts
+// After awaiting connectSupport(currentUserId):
+await inferenc.trackEvent('report.exported', { report_type: 'summary', format: 'pdf' });
+```
+
+Migrate backend Intercom event jobs to `trackEvent` from `@inferenc/sdk/server` using the immutable Cognito subject from the job's authenticated ownership record. Keep the signing secret server-only. Use `userName` for an optional profile name, because `name` is the event name. Do not use a workspace ID as the user ID.
+
+```js
+import { trackEvent } from '@inferenc/sdk/server';
+await trackEvent({
+  secret: process.env.INFERENC_IDENTITY_SECRET,
+  embedHash: process.env.INFERENC_EMBED_HASH,
+  userId: job.cognitoSubject,
+  name: 'subscription.activated',
+  eventId: job.inferencEventId, // persisted once when enqueuing; same on every retry
+  createdAt: job.occurredAt, // immutable UTC ISO timestamp
+  metadata: { plan: job.plan, workspace_id: job.workspaceId },
+});
+```
+
+Persist an ID of 1–128 alphanumeric/underscore/hyphen characters. Names are 1–100 characters, begin with a letter, and use letters/digits/underscore/dot/hyphen. Flatten metadata into at most 50 primitive values and 16KB UTF-8; do not pass entire Intercom payloads. Duplicate identical events return `duplicate: true`; changed content under the same ID returns 409. A fresh automatically generated ID on each job retry would create duplicates. Both browser and server events currently share the `sdk` source and provide customer context, not authoritative proof of payment.
+
+Signed-in initialization now creates the contact through the verified identify endpoint before reporting success, without a conversation, name or email. Server event ingestion also creates a contact without any browser visit. Verify contact creation before opening Help; confirm the event appears once on the contact timeline, retry the same job, test invalid signatures, and confirm account switching/logout abort pending event delivery. Deploy matching API/widget changes before relying on these methods.
+
+
+### Contact identity and existing records
+
+Use the same immutable user ID in browser identity tokens and server event jobs. Contacts are keyed by workspace and user ID, so changing email keeps the contact and two users sharing an email remain separate. Name and email are optional profile fields; do not ask the visitor to re-enter them. The contact persists before identify reports success. Propagate or report initialization failures and retry later rather than pretending connection succeeded.
+
+Existing signed conversations are linked to the stable contact when reopened. Old email-based contact records are retained; this release does not merge or delete legacy contacts or import Intercom history. New and restored signed conversations appear under their linked contact.
+
+Human inbox replies now reuse one request ID for automatic network retries and the Retry reply action. Reusing an ID with different content is rejected. The saved reply and human handoff are atomic; external notifications remain best effort after persistence. Web visitors receive saved replies through the widget's polling and history.
+
+## Map Reepl's Intercom user attributes (0.3.0)
+
+Intercom user and company attributes move to `update()` in the browser and `upsertContact()` / `upsertCompany()` on the server. Use the same immutable Cognito subject as `userId`.
+
+| Intercom | Inferenc |
+| --- | --- |
+| `user_id` | The signed token `sub` (`userId`). |
+| `email`, `name` | Token claims (verified) via `signWidgetIdentity` / `upsertContact`; browser values are stored as unverified. |
+| `phone` | `phone` |
+| Custom attributes (`plan`, `credits`, `trial_ends_at`, ...) | `attributes` using snake_case keys (`/^[a-z][a-z0-9_]{0,63}$/`); convert dates to ISO strings or epoch numbers; send `null` to delete. |
+| `company` (`company_id`, `name`, custom attributes) | `company: { company_id, name, attributes }`; Reepl workspace ID is the `company_id`. |
+| `last_request_at`, current page, UTM | `page: { url, title, referrer, utm_* }`. |
+| `Intercom("update", {...})` | `inferenc.update({...})`; call after the provider has identified. Calls made earlier are queued. |
+| Server-side `users.update` | `upsertContact({ secret, embedHash, userId, email, name, attributes, company })`. |
+
+Keep the profile Lambda as the authoritative source: send the full attribute set on login and the changed keys afterwards. Attributes are limited to 100 keys per contact and strings to 1000 characters, so drop large blobs and nested objects. Deploy the matching API and hosted widget first; verify in the inbox contact panel that attributes, company and last seen page appear.

package/docs/SERVER.md

@@ -0,0 +1,81 @@
+# Server integration
+
+The package provides the signer; your application provides authentication. Keep your existing Cognito, Auth.js, session-cookie, or other login flow. Create a backend endpoint that authenticates the caller, loads the current user's immutable ID, signs that identity, and returns the token without caching it.
+
+## Express-style example
+
+```js
+import { signWidgetIdentity } from '@inferenc/sdk/server';
+
+// requireSession is YOUR existing authentication middleware, not part of this SDK.
+app.get('/api/support/identity', requireSession, (req, res) => {
+  const user = req.user; // set by requireSession after validating the session
+  if (!user?.id) return res.status(401).json({ message: 'Sign in required' });
+  const token = signWidgetIdentity({
+    secret: process.env.INFERENC_IDENTITY_SECRET,
+    embedHash: process.env.INFERENC_EMBED_HASH,
+    userId: user.id,
+    name: user.name || undefined,
+    email: user.email || undefined,
+    expiresIn: 600,
+  });
+  res.set('Cache-Control', 'no-store, private').json({ token });
+});
+```
+
+Express is not a package dependency. The same function works in a Node Lambda or a Next.js route using the Node runtime. The helper does not work in an edge runtime without Node crypto support.
+
+## Inputs and signed claims
+
+| Input | JWT claim | Constraint |
+| --- | --- | --- |
+| `secret` | Never included | Server-only widget signing key, at least 32 bytes |
+| `embedHash` | `aud` | Nonempty widget ID, at most 128 characters |
+| `userId` | `sub` | Nonblank immutable app user ID, at most 256 characters |
+| `name`, `email` | Same name | Optional strings, at most 320 characters each |
+| `expiresIn` | Determines `exp` | Integer 60–3600 seconds; default 600 |
+| `now` | `iat` | Integer Unix seconds; omit outside deterministic tests |
+
+The header is `{ "alg": "HS256", "typ": "JWT" }`. Inferenc verifies the signature and expiry against the widget's private key registry. That registry also binds the widget to an organization and agent. A token for another user/widget cannot access the conversation.
+
+Do not accept a user ID or email from the request and sign it without authenticating the caller. Do not reuse an Intercom signing key. Do not log tokens or place them in URLs, persisted query caches, analytics, client bundles, or browser storage. Use HTTPS in production. Browser identity tokens are short-lived bearer credentials; token expiry is not a substitute for calling the SDK's `shutdown()` when your app logs out.
+
+Signed email is profile data your app supplies; Inferenc does not thereby verify mailbox ownership. A name or email is not required to start chat.
+
+## Provisioning and rotation
+
+Provision the key through your Inferenc administrator for the target widget. Self-service key creation is not exposed by this SDK. Install the same provisioned secret on the application's authenticated server. For rotation/revocation, update the registry and the server secret through the administrator; never distribute a platform-wide secret to customers. Each installation needs its own widget key.
+
+## Contact creation and custom events
+
+Awaiting signed-in `init()` or `identify()` now waits for `POST /v1/public/chat/identify`. It verifies the token and creates/resolves the user contact immediately; opening chat, sending a message, name and email are unnecessary. Identity failures reject and leave the widget in error state. This requires the matching hosted widget and API deployment.
+
+After identification, record browser activity:
+
+```js
+await inferenc.trackEvent('report.exported', { format: 'pdf', pages: 12 });
+```
+
+For business activity in an authenticated backend handler or job:
+
+```js
+import { trackEvent } from '@inferenc/sdk/server';
+
+await trackEvent({
+  secret: process.env.INFERENC_IDENTITY_SECRET,
+  embedHash: process.env.INFERENC_EMBED_HASH,
+  userId: authenticatedUser.id,
+  name: 'subscription.activated',
+  metadata: { plan: 'pro', seats: 3 },
+  eventId: 'subscription_abc_activated', // persist this with the job/outbox
+  createdAt: '2026-10-19T10:00:00.000Z', // persist original occurrence time
+});
+```
+
+The server helper derives a short-lived signed identity and calls the production API; it also creates/resolves the contact when there has been no browser visit. Optional `email` and `userName` are signed profile fields. Derive `userId` from your authenticated session or trusted job record, never a client-selected ID.
+
+Both methods return `{ event_id, contact_id, duplicate }`. Event names start with a letter and contain up to 100 letters, digits, underscores, dots or hyphens. Metadata is a flat JSON primitive map (string, finite number, boolean or null), at most 50 keys and 16KB UTF-8. `eventId` allows 1–128 letters, digits, underscores or hyphens. `createdAt` is an optional UTC ISO timestamp, no more than five minutes in the future.
+
+Without `eventId`, each call generates a new UUID. Transient network, 429 and 5xx failures retry up to twice with the same payload and ID. For job retries or retries across page reloads, persist and reuse the ID and original payload (including `createdAt` if supplied). The same ID with changed content returns 409; do not retry that conflict as a new ID. Logout/account changes abort in-flight browser requests and prevent retries under another account. An already accepted event cannot be undone by aborting the browser request.
+
+Events are contextual customer activity, not authoritative billing proofs: browser and server events currently share the `sdk` source and signed-user authentication. Never send secrets or payment credentials in metadata.

package/examples/node/sign-identity.mjs

@@ -0,0 +1,19 @@
+import { signWidgetIdentity } from '@inferenc/sdk/server';
+
+/** Call only after your server has authenticated the session. */
+export function supportIdentityResponse(authenticatedUser) {
+  if (!authenticatedUser?.id) {
+    return Response.json({ message: 'Sign in required' }, { status: 401 });
+  }
+  const token = signWidgetIdentity({
+    secret: process.env.INFERENC_IDENTITY_SECRET,
+    embedHash: process.env.INFERENC_EMBED_HASH,
+    userId: authenticatedUser.id,
+    name: authenticatedUser.name || undefined,
+    email: authenticatedUser.email || undefined,
+  });
+  return Response.json(
+    { token, user_id: authenticatedUser.id },
+    { headers: { 'Cache-Control': 'no-store, private' } },
+  );
+}

package/examples/react/SupportChat.tsx

@@ -0,0 +1,31 @@
+'use client';
+import { useEffect } from 'react';
+import inferenc from '@inferenc/sdk';
+
+// Supply userId from the app's authenticated state, not a text field.
+export function SupportChat({ userId, embedHash }: { userId: string | null; embedHash: string }) {
+  useEffect(() => {
+    if (!userId) { inferenc.shutdown(); return; }
+    let active = true;
+    void inferenc.init({
+      embedHash,
+      getIdentityToken: async () => {
+        if (!active) throw new Error('Account changed');
+        const response = await fetch('/api/support/identity', { credentials: 'same-origin', cache: 'no-store' });
+        if (!response.ok) throw new Error('Support identity unavailable');
+        const result = await response.json();
+        if (!active || result.user_id !== userId) throw new Error('Account changed');
+        return result.token;
+      },
+    }).catch(error => {
+      if (active && error.name !== 'AbortError') console.warn('Support chat unavailable');
+    });
+    // Mount this once in a stable app layout. Explicit logout must call shutdown
+    // before clearing auth. Do not tear down the widget on ordinary route changes.
+    return () => { active = false; };
+  }, [userId, embedHash]);
+  return null;
+}
+// This example expects the server to return { token, user_id }.
+// For Help buttons: await inferenc.show(). For logout: inferenc.shutdown().
+// Also render your app's retry/sign-in UI on inferenc:identity-error.

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@inferenc/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Inferenc support chat SDK: browser lifecycle and server-signed user identity.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/browser.d.ts",
+      "import": "./src/browser.js",
+      "default": "./src/browser.js"
+    },
+    "./server": {
+      "types": "./src/server.d.ts",
+      "browser": null,
+      "node": "./src/server.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs",
+    "examples"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "check": "tsc --noEmit",
+    "prepack": "npm test && npm run check"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "inferenc",
+    "chat",
+    "support",
+    "widget",
+    "sdk"
+  ],
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "@types/node": "22.19.0"
+  }
+}

package/src/attributes.js

@@ -0,0 +1,42 @@
+// Keep validation aligned with the hosted widget (apps/widget/src/script/widget.js mirrors the
+// block between the markers byte for byte, minus "export ") and the public contacts endpoint.
+// BEGIN MIRRORED: attributes
+export function contactPayload(input) {
+  const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value) && (Object.getPrototypeOf(value) === null || Object.getPrototypeOf(Object.getPrototypeOf(value)) === null);
+  const attributes = (value, label) => {
+    if (!plain(value) || Object.keys(value).length > 100) throw new TypeError(`${label} must be a flat map of at most 100 keys`);
+    for (const [key, item] of Object.entries(value)) {
+      if (!/^[a-z][a-z0-9_]{0,63}$/.test(key)) throw new TypeError(`Invalid ${label} key: ${key.slice(0, 64)}`);
+      if (typeof item === 'string' ? item.length > 1000 : item !== null && typeof item !== 'boolean' && !(typeof item === 'number' && Number.isFinite(item))) throw new TypeError(`${label}.${key} must be a string (max 1000 characters), finite number, boolean or null`);
+    }
+    return { ...value };
+  };
+  if (!plain(input)) throw new TypeError('Contact data must be an object');
+  const out = {};
+  for (const field of ['name', 'email', 'phone']) {
+    const value = input[field];
+    if (value === undefined) continue;
+    const max = field === 'phone' ? 64 : 320;
+    if (value !== null && (typeof value !== 'string' || value.length > max || (field === 'email' && value.trim() && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.trim())))) throw new TypeError(`Invalid ${field}`);
+    out[field] = value;
+  }
+  if (input.attributes !== undefined) out.attributes = attributes(input.attributes, 'attributes');
+  if (input.company !== undefined) {
+    const company = input.company;
+    if (!plain(company) || typeof company.company_id !== 'string' || !company.company_id.trim() || company.company_id.length > 128) throw new TypeError('company.company_id is required (max 128 characters)');
+    if (company.name !== undefined && (typeof company.name !== 'string' || company.name.length > 255)) throw new TypeError('Invalid company.name');
+    out.company = { company_id: company.company_id, ...(company.name === undefined ? {} : { name: company.name }), ...(company.attributes === undefined ? {} : { attributes: attributes(company.attributes, 'company.attributes') }) };
+  }
+  if (input.page !== undefined) {
+    if (!plain(input.page)) throw new TypeError('page must be an object');
+    const page = {};
+    for (const [key, value] of Object.entries(input.page)) {
+      if (!['url', 'title', 'referrer'].includes(key) && !/^utm_[a-z]{1,32}$/.test(key)) throw new TypeError(`Unknown page field: ${key.slice(0, 40)}`);
+      if (typeof value !== 'string' || value.length > (key === 'title' ? 500 : 2000) || ((key === 'url' || key === 'referrer') && value && !/^https?:\/\//i.test(value))) throw new TypeError(`Invalid page.${key}`);
+      page[key] = value;
+    }
+    out.page = page;
+  }
+  return out;
+}
+// END MIRRORED: attributes

package/src/browser.d.ts

@@ -0,0 +1,93 @@
+export type IdentityOptions =
+  | { identityToken: string; getIdentityToken?: never }
+  | { getIdentityToken: () => Promise<string>; identityToken?: never };
+export type BootOptions = IdentityOptions | { identityToken?: never; getIdentityToken?: never };
+export type InitOptions = BootOptions & {
+  embedHash: string;
+  loadTimeoutMs?: number;
+  /** Hide the default launcher bubble from first paint; open the panel with show(). */
+  hideDefaultLauncher?: boolean;
+  /** Override the widget origin (https, or http for localhost). Defaults to https://embed.inferenc.com. */
+  widgetOrigin?: string;
+  /** Override the API origin (https, or http for localhost). Defaults to https://api.inferenc.com. */
+  apiOrigin?: string;
+};
+/** Flat custom attributes. Keys match /^[a-z][a-z0-9_]{0,63}$/, strings are at most 1000 characters, at most 100 keys; null deletes a key. */
+export type ContactAttributes = Record<string, string | number | boolean | null>;
+export interface CompanyData {
+  /** Your stable company ID (max 128 characters). */
+  company_id: string;
+  name?: string;
+  attributes?: ContactAttributes;
+}
+export interface PageData {
+  url?: string;
+  title?: string;
+  referrer?: string;
+  utm_source?: string;
+  utm_medium?: string;
+  utm_campaign?: string;
+  utm_term?: string;
+  utm_content?: string;
+  [utm: `utm_${string}`]: string | undefined;
+}
+/** Contact data shared by browser `update()` and server `upsertContact()`. */
+export interface ContactData {
+  /** Stored as unverified unless it equals the signed identity token claim. */
+  name?: string | null;
+  /** Stored as unverified unless it equals the signed identity token claim. */
+  email?: string | null;
+  phone?: string | null;
+  attributes?: ContactAttributes;
+  company?: CompanyData;
+  page?: PageData;
+}
+export interface UpdateOptions extends ContactData { hideDefaultLauncher?: boolean; }
+export interface WidgetState {
+  /** identified means the backend verified identity and created/resolved a contact. */
+  status: 'uninitialized' | 'loading' | 'anonymous' | 'pending' | 'identified' | 'error';
+  identified: boolean;
+  isOpen: boolean;
+  /** false while the default launcher is hidden; true when uninitialized. */
+  launcherVisible: boolean;
+  /** Unread human/agent messages since the visitor last had the conversation open; 0 until the widget loads. */
+  unreadCount: number;
+}
+export interface InferencSDK {
+  init(options: InitOptions): Promise<void>;
+  boot(options?: BootOptions): Promise<void>;
+  identify(options: IdentityOptions): Promise<void>;
+  /** Synchronous: call before clearing your app's logged-in user. */
+  shutdown(): void;
+  trackEvent(name: string, metadata?: EventMetadata, options?: EventOptions): Promise<EventReceipt>;
+  show(): Promise<void>;
+  hide(): Promise<void>;
+  /**
+   * Open the panel on a new, empty message. `prefill` fills the composer for the visitor to
+   * review and send; it is never sent automatically (max 2000 characters).
+   */
+  showNewMessage(prefill?: string): Promise<void>;
+  /**
+   * Open the panel on the conversation list. Signed-in users see their recent conversations;
+   * anonymous visitors have a single conversation, which opens directly.
+   */
+  showMessages(): Promise<void>;
+  /** Change widget behaviour at runtime, e.g. hide the launcher while a cookie banner is up. */
+  update(options: UpdateOptions): Promise<void>;
+  /** Called when the panel opens (also emitted as a `inferenc:show` window event). Returns an unsubscribe function. */
+  onShow(callback: () => void): () => void;
+  /** Called when the panel closes (also emitted as a `inferenc:hide` window event). Returns an unsubscribe function. */
+  onHide(callback: () => void): () => void;
+  /** Called with the new unread count whenever it changes (also emitted as `inferenc:unread-count`, detail `{ count }`). Returns an unsubscribe function. */
+  onUnreadCountChange(callback: (count: number) => void): () => void;
+  getState(): WidgetState;
+}
+export declare const inferenc: InferencSDK;
+export default inferenc;
+
+export type EventMetadata = Record<string, string | number | boolean | null>;
+export interface EventOptions { eventId?: string; createdAt?: string; }
+export interface EventReceipt { event_id: string; contact_id: string; duplicate: boolean; }
+
+/** Maps free-form legacy names to a valid snake_case event name; throws TypeError when nothing usable remains. */
+export declare function normalizeEventName(name: string): string;

package/src/browser.js

@@ -0,0 +1,173 @@
+export { normalizeEventName } from './events.js';
+import { contactPayload } from './attributes.js';
+const stateKey = Symbol.for('inferenc.sdk.v1');
+const defaultWidgetOrigin = 'https://embed.inferenc.com';
+const cancelled = () => Object.assign(new Error('Inferenc operation cancelled by a newer identity or logout'), { name: 'AbortError' });
+function state() {
+  if (typeof window === 'undefined' || typeof document === 'undefined') throw new Error('Inferenc.init must run in a browser, after client hydration');
+  return window[stateKey] ??= { embedHash: null, loading: null, runtime: null, generation: 0, resetOnReady: false, error: false };
+}
+function identityOptions(options = {}, required = false) {
+  if (!options || typeof options !== 'object') throw new TypeError('Identity options must be an object');
+  const { identityToken, getIdentityToken } = options;
+  if (identityToken !== undefined && getIdentityToken !== undefined) throw new TypeError('Supply only one of identityToken or getIdentityToken');
+  if (identityToken !== undefined && (typeof identityToken !== 'string' || !identityToken)) throw new TypeError('identityToken must be a non-empty string');
+  if (getIdentityToken !== undefined && typeof getIdentityToken !== 'function') throw new TypeError('getIdentityToken must be a function');
+  if (required && identityToken === undefined && getIdentityToken === undefined) throw new TypeError('identify requires identityToken or getIdentityToken');
+  return getIdentityToken !== undefined ? { getIdentityToken } : identityToken !== undefined ? { identityToken } : {};
+}
+// https only, or http for localhost / 127.0.0.1. Returns the normalised origin.
+function safeOrigin(value, name) {
+  if (value === undefined) return undefined;
+  try {
+    const url = new URL(value);
+    const local = url.hostname === 'localhost' || url.hostname === '127.0.0.1';
+    if (url.protocol === 'https:' || (url.protocol === 'http:' && local)) return url.origin;
+  } catch { /* handled below */ }
+  throw new TypeError(`Invalid ${name}`);
+}
+function load(s, embedHash, timeoutMs, settings = {}) {
+  if (s.embedHash && s.embedHash !== embedHash) throw new Error('A different widget is already initialized; use one embedHash per page');
+  if (s.loading) return s.loading;
+  if (window.Inferenc || document.querySelectorAll('script[src*="embed.inferenc.com/widget-loader.js"], script[src*="embed.inferenc.com/api/widget"], script[src$="/widget-loader.js"][data-embed-hash]').length) {
+    throw new Error('Remove the existing Inferenc script integration before using the npm SDK');
+  }
+  s.embedHash = embedHash;
+  s.loading = new Promise((resolve, reject) => {
+    const script = document.createElement('script');
+    let settled = false;
+    const finish = (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      window.removeEventListener('inferenc:ready', ready);
+      if (error) { s.error = true; reject(error); return; }
+      s.runtime = window.Inferenc;
+      if (s.resetOnReady) { s.runtime.shutdown(); s.resetOnReady = false; }
+      resolve(s.runtime);
+    };
+    const ready = () => {
+      const runtime = window.Inferenc;
+      if (!runtime || !['boot','identify','shutdown','show','hide','getState'].every(k => typeof runtime[k] === 'function')) {
+        finish(new Error('Inferenc loaded an incompatible widget runtime')); return;
+      }
+      finish();
+    };
+    const timer = setTimeout(() => finish(new Error('Inferenc widget load timed out; check the allowed domains and reload to retry')), timeoutMs);
+    window.addEventListener('inferenc:ready', ready);
+    script.addEventListener('error', () => finish(new Error('Inferenc widget failed to load; reload to retry')), { once: true });
+    script.src = `${settings.widgetOrigin ?? defaultWidgetOrigin}/widget-loader.js`;
+    script.dataset.embedHash = embedHash;
+    if (settings.widgetOrigin) script.dataset.widgetOrigin = settings.widgetOrigin;
+    if (settings.apiOrigin) script.dataset.apiOrigin = settings.apiOrigin;
+    if (settings.hideDefaultLauncher) script.dataset.hideLauncher = 'true';
+    script.async = true;
+    document.head.appendChild(script);
+  });
+  return s.loading;
+}
+// Widget events are plain window CustomEvents, so subscribing works before init resolves
+// and for script-tag users too. Returns an idempotent unsubscribe function.
+function subscribe(name, callback, pick) {
+  if (typeof callback !== 'function') throw new TypeError('callback must be a function');
+  if (typeof window === 'undefined') return () => {};
+  const listener = (event) => {
+    const value = pick ? pick(event) : undefined;
+    if (value === null) return;
+    try { callback(value); } catch (error) { console.error('Inferenc callback failed', error); }
+  };
+  window.addEventListener(name, listener);
+  return () => window.removeEventListener(name, listener);
+}
+const unreadCount = (event) => {
+  const count = event?.detail?.count;
+  return Number.isInteger(count) && count >= 0 ? count : null;
+};
+async function operate(method, options) {
+  const s = state();
+  if (!s.loading) throw new Error('Call and await Inferenc.init first');
+  const version = ++s.generation;
+  const runtime = await s.loading;
+  if (version !== s.generation) throw cancelled();
+  await runtime[method](options);
+  if (version !== s.generation) throw cancelled();
+}
+async function readyRuntime(method) {
+  const s = state(); if (!s.loading) throw new Error('Call and await Inferenc.init first');
+  const version = s.generation, runtime = await s.loading;
+  if (version !== s.generation) throw cancelled();
+  if (typeof runtime[method] !== 'function') throw new Error(`Hosted widget does not support ${method}; reload after updating it`);
+  return runtime;
+}
+export const inferenc = {
+  async init(options) {
+    if (!options || typeof options.embedHash !== 'string' || !/^[a-zA-Z0-9_-]{1,128}$/.test(options.embedHash)) throw new TypeError('A valid embedHash is required');
+    const identity = identityOptions(options);
+    const timeoutMs = options.loadTimeoutMs ?? 20000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120000) throw new TypeError('loadTimeoutMs must be between 1 and 120000');
+    if (options.hideDefaultLauncher !== undefined && typeof options.hideDefaultLauncher !== 'boolean') throw new TypeError('hideDefaultLauncher must be a boolean');
+    const widgetOrigin = safeOrigin(options.widgetOrigin, 'widgetOrigin');
+    const apiOrigin = safeOrigin(options.apiOrigin, 'apiOrigin');
+    const s = state();
+    load(s, options.embedHash, timeoutMs, { widgetOrigin, apiOrigin, hideDefaultLauncher: options.hideDefaultLauncher });
+    await operate('boot', identity);
+  },
+  async boot(options = {}) { await operate('boot', identityOptions(options)); },
+  async identify(options) { await operate('identify', identityOptions(options, true)); },
+  async trackEvent(name, metadata = {}, options = {}) {
+    const s = state(); if (!s.loading) throw new Error('Call and await Inferenc.init first');
+    const version = s.generation, runtime = await s.loading;
+    if (version !== s.generation) throw cancelled();
+    if (typeof runtime.trackEvent !== 'function') throw new Error('Hosted widget does not support events; reload after updating it');
+    const receipt = await runtime.trackEvent(name, metadata, options);
+    if (version !== s.generation) throw cancelled();
+    return receipt;
+  },
+  shutdown() {
+    if (typeof window === 'undefined') return;
+    const s = window[stateKey];
+    if (!s) return;
+    ++s.generation;
+    if (s.runtime) s.runtime.shutdown();
+    else if (s.loading) s.resetOnReady = true;
+  },
+  async show() {
+    const s = state(); if (!s.loading) throw new Error('Call and await Inferenc.init first');
+    const version = s.generation, runtime = await s.loading;
+    if (version !== s.generation) throw cancelled();
+    runtime.show();
+  },
+  async update(options) {
+    if (!options || typeof options !== 'object') throw new TypeError('update options must be an object');
+    if (options.hideDefaultLauncher !== undefined && typeof options.hideDefaultLauncher !== 'boolean') throw new TypeError('hideDefaultLauncher must be a boolean');
+    const contact = contactPayload(Object.fromEntries(['name', 'email', 'phone', 'attributes', 'company', 'page'].filter(key => options[key] !== undefined).map(key => [key, options[key]])));
+    const s = state(); if (!s.loading) throw new Error('Call and await Inferenc.init first');
+    const version = s.generation, runtime = await s.loading;
+    if (version !== s.generation) throw cancelled();
+    if (typeof runtime.update !== 'function') throw new Error('Hosted widget does not support update; reload after updating it');
+    // Contact data resolves once sent (identified visitors) or queued (anonymous visitors).
+    await runtime.update({ ...(options.hideDefaultLauncher === undefined ? {} : { hideDefaultLauncher: options.hideDefaultLauncher }), ...contact });
+  },
+  async hide() {
+    const s = state(); if (!s.loading) throw new Error('Call and await Inferenc.init first');
+    const version = s.generation, runtime = await s.loading;
+    if (version !== s.generation) throw cancelled();
+    runtime.hide();
+  },
+  async showNewMessage(prefill) {
+    if (prefill !== undefined && (typeof prefill !== 'string' || prefill.length > 2000)) throw new TypeError('prefill must be a string of at most 2000 characters');
+    (await readyRuntime('showNewMessage')).showNewMessage(prefill ?? '');
+  },
+  async showMessages() { (await readyRuntime('showMessages')).showMessages(); },
+  /** Called when the panel opens. Returns an unsubscribe function. */
+  onShow(callback) { return subscribe('inferenc:show', callback); },
+  /** Called when the panel closes. Returns an unsubscribe function. */
+  onHide(callback) { return subscribe('inferenc:hide', callback); },
+  /** Called with the new unread count whenever it changes. Returns an unsubscribe function. */
+  onUnreadCountChange(callback) { return subscribe('inferenc:unread-count', callback, unreadCount); },
+  getState() {
+    const s = typeof window !== 'undefined' ? window[stateKey] : null;
+    return s?.runtime ? s.runtime.getState() : { status: s?.error ? 'error' : s?.loading ? 'loading' : 'uninitialized', identified: false, isOpen: false, launcherVisible: true, unreadCount: 0 };
+  },
+};
+export default inferenc;

package/src/events.js

@@ -0,0 +1,19 @@
+// Keep validation aligned with the hosted widget and public events endpoint.
+export function eventPayload(name, metadata = {}, options = {}) {
+  if (typeof name !== 'string' || !/^[A-Za-z][A-Za-z0-9_.-]{0,99}$/.test(name)) throw new TypeError('Invalid event name');
+  const eventId = options.eventId ?? crypto.randomUUID();
+  if (typeof eventId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(eventId)) throw new TypeError('Invalid eventId');
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata) || (Object.getPrototypeOf(metadata) !== null && Object.getPrototypeOf(Object.getPrototypeOf(metadata)) !== null) || Object.keys(metadata).length > 50) throw new TypeError('metadata must be a flat map of at most 50 keys');
+  for (const value of Object.values(metadata)) if (value !== null && !['string', 'number', 'boolean'].includes(typeof value) || typeof value === 'number' && !Number.isFinite(value)) throw new TypeError('metadata values must be finite JSON primitives');
+  if (new TextEncoder().encode(JSON.stringify(metadata)).length > 16384) throw new TypeError('metadata exceeds 16KB');
+  if (options.createdAt !== undefined && (typeof options.createdAt !== 'string' || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?Z$/.test(options.createdAt) || !Number.isFinite(Date.parse(options.createdAt)) || Date.parse(options.createdAt) > Date.now() + 300000)) throw new TypeError('Invalid createdAt UTC timestamp');
+  return { event_id: eventId, name, metadata, ...(options.createdAt === undefined ? {} : { created_at: options.createdAt }) };
+}
+// Maps free-form legacy names (e.g. "Upgrade Button - Click") to a valid snake_case event name.
+export function normalizeEventName(name) {
+  if (typeof name !== 'string') throw new TypeError('Event name must be a string');
+  let normalized = name.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+  if (!normalized) throw new TypeError('Event name has no usable characters');
+  if (/^[0-9]/.test(normalized)) normalized = `e_${normalized}`;
+  return normalized.slice(0, 100).replace(/_+$/, '');
+}

package/src/server.d.ts

@@ -0,0 +1,39 @@
+export interface SignWidgetIdentityOptions {
+  /** Server-only signing secret provisioned for this widget. Never expose it to clients. */
+  secret: string;
+  embedHash: string;
+  /** Immutable user ID read from your authenticated server session. */
+  userId: string;
+  name?: string;
+  email?: string;
+  /** Lifetime in seconds: 60–3600; default 600. */
+  expiresIn?: number;
+  /** Unix timestamp in seconds. Omit in production. */
+  now?: number;
+}
+export declare function signWidgetIdentity(options: SignWidgetIdentityOptions): string;
+
+import type { EventMetadata, EventOptions, EventReceipt } from './browser.js';
+export interface TrackEventOptions extends EventOptions {
+  secret: string;
+  embedHash: string;
+  userId: string;
+  name: string;
+  metadata?: EventMetadata;
+  email?: string;
+  userName?: string;
+}
+export declare function trackEvent(options: TrackEventOptions): Promise<EventReceipt>;
+
+import type { CompanyData, ContactData } from './browser.js';
+export interface UpsertContactOptions extends ContactData {
+  secret: string;
+  embedHash: string;
+  userId: string;
+}
+export interface ContactReceipt { contact_id: string; user_id: string; contact?: Record<string, unknown>; }
+/** Create or update a contact. name and email are signed by your secret and stored as verified. */
+export declare function upsertContact(options: UpsertContactOptions): Promise<ContactReceipt>;
+export declare function upsertCompany(options: { secret: string; embedHash: string; userId: string; company: CompanyData }): Promise<ContactReceipt>;
+
+export { normalizeEventName } from './browser.js';

package/src/server.js

@@ -0,0 +1,61 @@
+/** Server-only helper. Never ship the signing secret to a browser. */
+import { createHmac } from 'node:crypto';
+export function signWidgetIdentity({ secret, embedHash, userId, name, email, expiresIn = 600, now = Math.floor(Date.now() / 1000) }) {
+  if (typeof secret !== 'string' || Buffer.byteLength(secret) < 32) throw new Error('Signing secret must contain at least 32 bytes');
+  if (typeof userId !== 'string' || !userId.trim() || userId.length > 256) throw new Error('Invalid userId');
+  if (typeof embedHash !== 'string' || !embedHash || embedHash.length > 128) throw new Error('Invalid embedHash');
+  if (!Number.isInteger(expiresIn) || expiresIn < 60 || expiresIn > 3600 || !Number.isInteger(now)) throw new Error('Token lifetime must be 60–3600 seconds');
+  const claims = { sub: userId, aud: embedHash, iat: now, exp: now + expiresIn };
+  for (const [field, value] of Object.entries({ name, email })) {
+    if (value !== undefined) {
+      if (typeof value !== 'string' || value.length > 320) throw new Error(`Invalid ${field}`);
+      claims[field] = value;
+    }
+  }
+  const encode = value => Buffer.from(JSON.stringify(value)).toString('base64url');
+  const payload = `${encode({ alg: 'HS256', typ: 'JWT' })}.${encode(claims)}`;
+  return `${payload}.${createHmac('sha256', secret).update(payload).digest('base64url')}`;
+}
+
+import { eventPayload } from './events.js';
+export { normalizeEventName } from './events.js';
+import { contactPayload } from './attributes.js';
+// Signed POST to a public SDK route, retrying network errors, 429 and 5xx with the same body.
+async function post(route, label, token, body, valid) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      const response = await fetch(`https://api.inferenc.com/v1/public/chat/${route}`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Widget ${token}` },
+        body, signal: AbortSignal.timeout(15000), redirect: 'error',
+      });
+      if (!response.ok) throw Object.assign(new Error(`Inferenc ${label} failed (${response.status})`), { status: response.status });
+      const result = await response.json();
+      if (!result.success || !valid(result.data)) throw Object.assign(new Error(`Invalid Inferenc ${label} response`), { status: 502 });
+      return result.data;
+    } catch (error) {
+      if (attempt === 2 || error.status && error.status !== 429 && error.status < 500) throw error;
+    }
+  }
+}
+/** Deliver contextual events. Persist eventId in your job/outbox for safe retries. */
+export async function trackEvent({ secret, embedHash, userId, name, metadata = {}, eventId, createdAt, email, userName }) {
+  const body = JSON.stringify(eventPayload(name, metadata, { eventId, createdAt }));
+  const token = signWidgetIdentity({ secret, embedHash, userId, name: userName, email });
+  return post('events', 'event', token, body, data => data?.event_id && data?.contact_id);
+}
+/**
+ * Create or update a contact. The signing secret vouches for name and email, so they are stored as
+ * verified; phone, attributes (null deletes a key) and company are merged into the contact.
+ */
+export async function upsertContact({ secret, embedHash, userId, email, name, phone, attributes, company, page }) {
+  const body = JSON.stringify(contactPayload({ name, email, phone, attributes, company, page }));
+  const token = signWidgetIdentity({ secret, embedHash, userId, name, email });
+  return post('contacts', 'contact', token, body, data => data?.contact_id);
+}
+/** Attach or update the company of an existing user (creates the contact if needed). */
+export async function upsertCompany({ secret, embedHash, userId, company }) {
+  if (company === undefined) throw new TypeError('company is required');
+  const body = JSON.stringify(contactPayload({ company }));
+  const token = signWidgetIdentity({ secret, embedHash, userId });
+  return post('contacts', 'company', token, body, data => data?.contact_id);
+}