@intray/live 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lowside Labs
+
+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

@@ -0,0 +1,97 @@
+# @intray/live
+
+Live session watching for [Intray](https://intray.ai). While someone on your team has the Live view open, the SDK streams the signed-in customer's page to them. Nobody watching means nothing is captured. Intray stores no replay.
+
+```sh
+npm install @intray/live
+```
+
+## How the parts connect
+
+```
+createLiveWatch (browser) -> your backend route -> Intray POST /v1/support/sessions
+```
+
+The browser never holds the Intray key. Your backend reads the signed-in user from its own session, asks Intray for a short-lived recorder token, and returns it.
+
+## Server
+
+Create the application in Intray under Live, Manage applications, with your product's exact HTTPS origin. Store its key as `INTRAY_LIVE_KEY`.
+
+```ts
+// Server only. Take the user and account from your own session.
+export async function bootstrapLiveSession(req: Request, sessionId: string) {
+  const user = await requireUser(req);
+
+  const res = await fetch(process.env.INTRAY_LIVE_BOOTSTRAP_URL!, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${process.env.INTRAY_LIVE_KEY}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      sessionId,
+      userId: user.id,
+      accountId: user.accountId,
+      displayName: user.name,
+      origin: process.env.SITE_URL,
+    }),
+  });
+  if (!res.ok) throw new Error("Intray refused the live session");
+  return res.json(); // { token, expiresAt, serverUrl, sessionId }
+}
+```
+
+Do not let browser arguments choose `userId`, `accountId`, or `origin`. Tokens last 120 seconds. The SDK calls `getSession` again, with the same id, on every reconnect and renewal.
+
+## Browser
+
+```ts
+import { createLiveWatch } from "@intray/live";
+
+const live = createLiveWatch({
+  getSession: (sessionId) => api.bootstrapLiveSession({ sessionId }),
+  isPageAllowed: () => location.pathname.startsWith("/app"),
+  blockSelector: "[data-support-private]",
+});
+
+await live.start();
+
+// On logout or account switch
+live.destroy();
+```
+
+### Options
+
+| Option               | Type                                    | Notes                                                                                                           |
+| -------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `getSession`         | `(sessionId) => Promise<LiveBootstrap>` | Required. Calls your backend route.                                                                             |
+| `isPageAllowed`      | `() => boolean`                         | Checked as the page changes. Capture pauses while it returns false.                                             |
+| `blockSelector`      | `string`                                | Added to the default block list, which already has `[data-private]`. A blocked element renders as an empty box. |
+| `maskTextSelector`   | `string`                                | Defaults to `*`. All text is masked.                                                                            |
+| `publicTextSelector` | `string`                                | Opt-in for reviewed static labels, for example `[data-support-public]`.                                         |
+| `onState`            | `(state) => void`                       | `connecting`, `idle`, `live`, `paused`, `hidden`, `reconnecting`, `unavailable`, `stopped`.                     |
+| `assistance`         | `boolean`                               | Off by default. Lets an operator request customer-approved clicks on `data-support-control` buttons.            |
+| `controlsContainer`  | `HTMLElement`                           | Where the consent prompt mounts. Defaults to a floating prompt.                                                 |
+
+### Methods
+
+`start()`, `stopSharing()`, `resumeSharing()`, `destroy()`. Use `stopSharing` and `resumeSharing` to give customers their own switch. Destroy the instance on logout or account change. Do not reuse it across identities.
+
+## Privacy defaults
+
+- All text and every input value are masked before they leave the browser.
+- Password and payment fields, canvas, and iframes are never sent.
+- URL query strings and hashes are stripped.
+- `.rr-mask`, `[data-support-mask]`, `[data-live-mask]`, inputs, and editable content stay masked even inside a public marker.
+- Never put `publicTextSelector` markers on a container that can hold customer content.
+
+Viewing shows no indicator in your product. Disclose live viewing in your privacy policy and terms.
+
+## Bundle
+
+ESM only, browser target ES2022. The recorder loads on demand, so `rrweb` stays out of your first chunk. `rrweb` is pinned as a dependency.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+/** Always blocked. A configured `blockSelector` adds to this list and cannot shorten it. */
+declare const DEFAULT_BLOCK_SELECTOR: string;
+/** Pilot default: every text node is masked. */
+declare const DEFAULT_MASK_TEXT_SELECTOR = "*";
+
+/**
+ * What the host backend returns from `POST /v1/support/sessions`.
+ *
+ * Declared here, not re-exported, because the protocol package is private and
+ * a published type file cannot import it. The check below fails the build when
+ * the two drift.
+ */
+type LiveBootstrap = {
+    token: string;
+    expiresAt: number;
+    serverUrl: string;
+    sessionId: string;
+};
+
+type LiveWatchState = "connecting"
+/** Connected and sharing. Nobody is watching, so nothing is captured. */
+ | "idle"
+/** A viewer is present and the page is being captured. */
+ | "live"
+/** The user stopped sharing. */
+ | "paused"
+/** The tab is hidden or the page is not allowed. */
+ | "hidden" | "reconnecting"
+/** The live service refused this session. No further attempts are made. */
+ | "unavailable" | "stopped";
+type LiveWatchOptions = {
+    getSession: (sessionId: string) => Promise<LiveBootstrap>;
+    onState?: (state: string) => void;
+    /** Place the control consent prompt in the product layout instead of an overlay. */
+    controlsContainer?: HTMLElement;
+    /** Explicitly enable customer-approved clicks on data-support-control buttons. Defaults off. */
+    assistance?: boolean;
+    blockSelector?: string;
+    maskTextSelector?: string;
+    publicTextSelector?: string;
+    isPageAllowed?: () => boolean;
+};
+type LiveWatch = {
+    start(): Promise<void>;
+    stopSharing(): void;
+    resumeSharing(): void;
+    destroy(): void;
+};
+
+/**
+ * Shares the current page with Intray staff while one of them is watching.
+ *
+ * `getSession` must call the host app's authenticated backend, which returns a
+ * short-lived recorder token for the given session id. It is called again, with
+ * the same id, on every reconnect and renewal.
+ */
+declare function createLiveWatch(options: LiveWatchOptions): LiveWatch;
+
+export { DEFAULT_BLOCK_SELECTOR, DEFAULT_MASK_TEXT_SELECTOR, type LiveBootstrap, type LiveWatch, type LiveWatchOptions, type LiveWatchState, createLiveWatch };