@jam.dev/recording-links 0.2.0 → 0.3.0-electron.5

package/README.md

@@ -183,6 +183,354 @@ type RecorderSingleton = {
 };
 ```
 
+## Electron
+
+Jam Recording Links can be integrated into your Electron app to enable seamless
+bug reporting with screen recordings.
+
+### 1. Initialize Jam Electron (Required)
+
+Initialize the SDK in your main process before `app.whenReady()`:
+
+```typescript
+import { app, BrowserWindow } from "electron";
+import * as jam from "@jam.dev/recording-links/electron";
+
+jam.initialize({
+  // Optional: Customize the session if using non-default or multiple sessions.
+  // A Recorder can only capture logs from windows belonging to the same session.
+  // Defaults to session.defaultSession if not provided.
+  // defaultSession: session.defaultSession,
+
+  // Optional: Customize the display media request handler.
+  // By default, Jam installs a handler that auto-selects capture sources.
+  // Set to null if you want to handle display media requests yourself.
+  // defaultDisplayMediaRequestHandler: null,
+
+  openRecorderWindow(session) {
+    return new BrowserWindow({
+      width: 1000,
+      height: 700,
+      webPreferences: {
+        // Required to allow loading Jam's remote recorder scripts from *.jam.dev.
+        // Alternative: Use session.webRequest.onHeadersReceived() to set CSP headers
+        // allowing *.jam.dev for default-src, script-src, and worker-src.
+        allowRunningInsecureContent: true,
+        nodeIntegration: false,
+        contextIsolation: true,
+        sandbox: true,
+      },
+    });
+  },
+  async loadRecorderPage(win, data) {
+    // Load your app with jam-* query parameters
+    return win.loadURL(`https://my-app.com${data.search}`);
+    // or: return win.loadFile("index.html", data);
+  },
+});
+```
+
+**What this does:**
+- Installs display media request handler for screen capture on the default session
+- Configures window creation and content loading for recorder
+- Manages recorder window lifecycle per session
+
+---
+
+### 2. Handle Incoming Jam Links (Recommended)
+
+**Register your app's protocol** (if not already done):
+
+Add to your `package.json` electron-builder config:
+
+```json
+{
+  "build": {
+    "protocols": {
+      "name": "my-app",
+      "schemes": ["myapp"]
+    }
+  }
+}
+```
+
+**Wire up protocol handlers** to open Jam recordings:
+
+```typescript
+import { app } from "electron";
+import * as jam from "@jam.dev/recording-links/electron";
+
+// macOS: Handle protocol URLs
+app.on("open-url", (event, url) => {
+  event.preventDefault();
+  const [cleanUrl, recorderWindow] = jam.openUrl(url);
+
+  if (recorderWindow) {
+    recorderWindow.focus();
+  }
+  // cleanUrl has jam-* params removed for your main window
+});
+
+// Windows/Linux: Handle second instance
+// Note: Remember to implement app.requestSingleInstanceLock() in your app
+app.on("second-instance", (event, commandLine) => {
+  const url = commandLine.find((arg) => arg.startsWith("myapp://"));
+  if (url) {
+    const [cleanUrl, recorderWindow] = jam.openUrl(url);
+    if (recorderWindow) {
+      recorderWindow.focus();
+    }
+  }
+});
+```
+
+**Result:** Links like `myapp://open?jam-recording=abc123` will launch your app and open the recorder.
+
+---
+
+### 3. Enable In-App Recording (Optional)
+
+Add a menu item to trigger recordings from within your app:
+
+```typescript
+import { Menu } from "electron";
+import * as jam from "@jam.dev/recording-links/electron";
+
+const template = [
+  {
+    label: "Help",
+    submenu: [
+      {
+        label: "Report a Bug",
+        click: () => {
+          jam.openRecorder("your-recording-id-here");
+        },
+      },
+    ],
+  },
+];
+
+Menu.setApplicationMenu(Menu.buildFromTemplate(template));
+```
+
+**Test:** Click "Report a Bug" → Recorder window opens and screen capture starts.
+
+---
+
+### API Reference
+
+#### `initialize(config)`
+
+Initializes the Jam SDK for Electron. Must be called before using other Jam functions.
+
+**Parameters:**
+
+- `config.defaultSession?: Session` - The session to install display media handler on. Defaults to `session.defaultSession`. If using multiple sessions, install handlers on each session.
+
+- `config.defaultDisplayMediaRequestHandler?: DisplayMediaRequestHandler | null` - The display media request handler to install. In an upcoming version, this will introduce a "screen or window picker" UI to the Recorder window. Right now, it uses the OS picker on Mac, and default-selects the first window it sees in Windows + Linux. Set to `null` to handle display media requests yourself (see advanced example below).
+
+- `config.openRecorderWindow(session: Session): BrowserWindow` **(required)** - Function that creates and returns a BrowserWindow for the recorder. Called once per session when opening a recorder.
+
+- `config.loadRecorderPage(win: BrowserWindow, data: IJamData): Promise<void>` **(required)** - Function that loads your app with Jam recording parameters into the recorder window.
+
+**Advanced Example with Custom Display Media Handler:**
+
+```typescript
+import { BrowserWindow, desktopCapturer, session, webContents } from "electron";
+import * as jam from "@jam.dev/recording-links/electron";
+
+jam.initialize({
+  defaultDisplayMediaRequestHandler: null, // Don't install default handler
+  // ... other config
+});
+
+// Install custom handler per session
+session.defaultSession.setDisplayMediaRequestHandler(
+  async (request, callback) => {
+    const frame = request.frame;
+    const contents = frame ? webContents.fromFrame(frame) : null;
+    const win = contents ? BrowserWindow.fromWebContents(contents) : null;
+
+    if (jam.isJamRecorder(win)) {
+      const sources = await desktopCapturer.getSources({
+        types: ["screen", "window"],
+      });
+      jam.handleDisplayMediaRequest(sources, callback, win);
+    } else {
+      // Your app's own display media handling
+      callback({});
+    }
+  },
+  { useSystemPicker: true },
+);
+```
+
+#### `openRecorder(init, session?)`
+
+Opens a Jam recorder window. If a recorder window is already open for the session, focuses it and loads the new recording.
+
+**Parameters:**
+
+- `init: string | { recordingId: string; jamTitle?: string } | URLSearchParams` - Recording ID, data object, or URL parameters
+- `session?: Session` - Optional session (defaults to `defaultSession` from initialize)
+
+**Returns:** `BrowserWindow` - The recorder window (returns immediately, page loads asynchronously)
+
+**Examples:**
+
+```typescript
+// Open by recording ID
+jam.openRecorder("abc123");
+
+// Open with title
+jam.openRecorder({ recordingId: "abc123", jamTitle: "Bug Report" });
+
+// Open from URL parameters
+const params = new URLSearchParams("jam-recording=abc123&jam-title=Bug");
+jam.openRecorder(params);
+```
+
+#### `openUrl(url, session?)`
+
+Parses a URL, extracts Jam recording parameters, and opens the recorder if parameters are found. Returns the cleaned URL (with Jam params removed) and the recorder window if opened.
+
+**Parameters:**
+
+- `url: string | URL` - URL to parse (e.g., from protocol handler)
+- `session?: Session` - Optional session (defaults to `defaultSession` from initialize)
+
+**Returns:** `[string, BrowserWindow | null]` - Tuple of cleaned URL and recorder window (or null)
+
+**Example:**
+
+```typescript
+app.on("open-url", (event, url) => {
+  event.preventDefault();
+  const [cleanUrl, recorderWindow] = jam.openUrl(url);
+
+  if (recorderWindow) {
+    recorderWindow.focus();
+  } else {
+    // Open your main window with cleanUrl
+  }
+});
+```
+
+#### `isJamRecorder(win)`
+
+Checks if a BrowserWindow is a Jam recorder window.
+
+**Parameters:**
+
+- `win: BrowserWindow | null` - Window to check
+
+**Returns:** `boolean` - True if window is a Jam recorder
+
+**Example:**
+
+```typescript
+import { BrowserWindow } from "electron";
+import * as jam from "@jam.dev/recording-links/electron";
+
+const win = BrowserWindow.getFocusedWindow();
+if (jam.isJamRecorder(win)) {
+  console.log("This is a Jam recorder window");
+}
+```
+
+#### `handleDisplayMediaRequest(sources, callback, requester?)`
+
+Helper function for custom display media request handlers. Filters sources (excludes recorder window and DevTools), selects the best source, and calls the callback.
+
+In an upcoming version, this function will implement a handshake with the Recorder window to display a "screen or window picker" UI. Right now, it auto-selects the first app window (or first screen if no windows are available).
+
+**Parameters:**
+
+- `sources: DesktopCapturerSource[]` - Sources from `desktopCapturer.getSources()`
+- `callback: DisplayMediaRequestHandlerCallback` - Callback from display media request handler
+- `requester?: BrowserWindow | null` - The requesting window (to exclude from sources)
+
+**Example:**
+
+```typescript
+import { BrowserWindow, desktopCapturer, session, webContents } from "electron";
+import * as jam from "@jam.dev/recording-links/electron";
+
+session.defaultSession.setDisplayMediaRequestHandler(
+  async (request, callback) => {
+    const sources = await desktopCapturer.getSources({
+      types: ["screen", "window"],
+    });
+
+    const frame = request.frame;
+    const win = frame
+      ? BrowserWindow.fromWebContents(webContents.fromFrame(frame))
+      : null;
+
+    jam.handleDisplayMediaRequest(sources, callback, win);
+  },
+);
+```
+
+#### `IJamData` Interface
+
+Data structure representing Jam recording parameters.
+
+```typescript
+interface IJamData {
+  recordingId: string; // Jam recording ID
+  jamTitle: string | undefined | null; // Optional recording title
+  state: string | undefined | null; // Optional JWT state
+  searchParams: URLSearchParams; // jam-* query parameters
+  search: string; // Query string with '?' prefix (or empty)
+}
+```
+
+---
+
+## What Jam Recording Links Enables for Your Electron App
+
+Users can report bugs with one click:
+
+- From your app menu → Instant screen recording starts
+- From Jam Recording Links (via Slack, email) → App launches and recording begins
+- Zero configuration of screen capture or window management
+
+## What the SDK Provides
+
+### Window Architecture
+
+- Creates separate recorder window when `jam-*` query parameters detected
+- Maintains main window alongside recorder (multi-window pattern)
+- Auto-focuses or reuses existing recorder window if already open
+- Prevents recorder window from closing while recording
+
+### Screen Capture
+
+- Filters capture sources to exclude recorder window (prevents recursive capture)
+- Auto-excludes DevTools windows from source list
+- Configures `desktopCapturer` with appropriate permissions
+- TEMPORARY: Implements source selection strategy: prefer app windows, then screens
+    - WILL BE REPLACED with user source picker in future release
+
+### Protocol Integration
+
+- Parses `yourapp://open?jam-recording=ID` format URLs
+- Routes protocol requests to dual-window opener
+- Handles cross-platform differences (macOS `open-url` vs Windows/Linux `second-instance`)
+- Validates and extracts `jam-*` query parameters
+
+### Developer Configuration
+
+**You provide:**
+
+- **Protocol scheme**: Your app's custom URL scheme (e.g., "notion", "slack")
+- **Web URLs**: Dev server (e.g., `http://localhost:3000`) and production path
+- **Recording IDs**: Which Jam recording to open for bug reports (coming soon: dynamic values via API)
+- **Trigger UI**: Where to place menu items or buttons in your app
+
+**SDK handles everything else.**
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, build commands, and release process.

package/lib/electron.d.ts

@@ -0,0 +1,193 @@
+import { BrowserWindow, type DesktopCapturerSource, type DisplayMediaRequestHandlerHandlerRequest, type Session, type WebFrameMain } from "electron";
+type DisplayMediaRequestHandler = (request: DisplayMediaRequestHandlerHandlerRequest, callback: DisplayMediaRequestHandlerCallback) => void | Promise<void>;
+type DisplayMediaRequestHandlerCallback = (streams: {
+    video?: WebFrameMain | {
+        id: string;
+        name: string;
+    } | undefined;
+    audio?: "loopback" | "loopbackWithMute" | WebFrameMain | undefined;
+    enableLocalEcho?: boolean | undefined;
+}) => void | Promise<void>;
+/**
+ * Initialize the Jam SDK for Electron.
+ *
+ * @example Basic setup
+ * ```typescript
+ * import { app, BrowserWindow } from 'electron';
+ * import * as jam from '@jam.dev/recording-links/electron';
+ *
+ * jam.initialize({
+ *   openRecorderWindow(session) {
+ *     return new BrowserWindow({
+ *       width: 1000,
+ *       height: 700,
+ *       webPreferences: {
+ *         allowRunningInsecureContent: true,
+ *         nodeIntegration: false,
+ *         contextIsolation: true,
+ *         sandbox: true,
+ *       },
+ *     });
+ *   },
+ *   async loadRecorderPage(win, data) {
+ *     await win.loadURL(`https://my-app.com${data.searchParams.toString()}`);
+ *   },
+ * });
+ * ```
+ *
+ * @example Multi-session app with custom display media handler
+ * ```typescript
+ * import { session, desktopCapturer, BrowserWindow } from 'electron';
+ * import * as jam from '@jam.dev/recording-links/electron';
+ *
+ * jam.initialize({
+ *   defaultDisplayMediaRequestHandler: null, // Use custom handler per session
+ *   openRecorderWindow(ses) {
+ *     const win = new BrowserWindow({
+ *       width: 1000,
+ *       height: 700,
+ *       webPreferences: {
+ *         allowRunningInsecureContent: true,
+ *         nodeIntegration: false,
+ *         contextIsolation: true,
+ *         sandbox: true,
+ *       },
+ *     });
+ *     win.on('closed', () => console.log('Recorder closed'));
+ *     return win;
+ *   },
+ *   async loadRecorderPage(win, data) {
+ *     const recordingId = data.searchParams.get('jam-recording');
+ *     await win.loadURL(`https://my-app.com/recorder?id=${recordingId}`);
+ *   },
+ * });
+ *
+ * // Install handler on a specific session
+ * const mySession = session.fromPartition('persist:my-session');
+ * mySession.setDisplayMediaRequestHandler(async (request, callback) => {
+ *   const frame = request.frame;
+ *   const win = frame ? BrowserWindow.fromWebContents(frame.webContents) : null;
+ *
+ *   if (jam.isJamRecorder(win)) {
+ *     const sources = await desktopCapturer.getSources({ types: ['screen', 'window'] });
+ *     jam.handleDisplayMediaRequest(sources, callback, win);
+ *   } else {
+ *     // Your app's default behavior
+ *     callback({});
+ *   }
+ * });
+ * ```
+ */
+export declare function initialize(config: {
+    /**
+     * The session upon which we will install Jam's display media request handler.
+     * If your app uses multiple sessions, please install a handler on each session
+     * for which Jam is installed; then in your handler, call
+     * `jam.handleDisplayMediaRequest(request, callback)`.
+     *
+     * @default session.defaultSession
+     */
+    defaultSession?: Session | undefined;
+    /**
+     * Jam.js for Electron requires setting a display media request handler,
+     * which defines the app's implementation for
+     * `navigator.mediaDevices.getDisplayMedia(...)` calls.
+     *
+     * By default, we use:
+     *
+     * ```
+     * defaultSession.setDisplayMediaRequestHandler(
+     *   (request, callback) => {
+     *     if (request.frame.url === "https://jam.dev") {
+     *       jam.handleDisplayMediaRequest(sources, callback);
+     *     }
+     *   }),
+     *   { useSystemPicker: true },
+     * );
+     * ```
+     *
+     * If your app manages multiple sessions, or sets its own display media
+     * request handler on the session, set this to `null` and either:
+     *
+     * - Select the default `source` and call the `callback` yourself; or
+     * - Call `jam.handleDisplayMediaRequest(sources, callback)` in your handler
+     *   when the request originates from a Jam-originating frame
+     */
+    defaultDisplayMediaRequestHandler?: DisplayMediaRequestHandler | null;
+    /**
+     * A function that takes one argument (a `Session` object) and opens a
+     * BrowserWindow we will use for recording.
+     *
+     * The window will be cached for reuse; when calling `loadRecorder`, Jam will
+     * only call this function if a previously-opened Recorder window for this
+     * session has been closed.
+     */
+    openRecorderWindow(ses: Session): BrowserWindow;
+    /**
+     * A function that takes two arguments—a `BrowserWindow` (opened by
+     * `openRecorderWindow`) and an `IJamData` object used to route the window
+     * to the proper recorder configuration.
+     */
+    loadRecorderPage(win: BrowserWindow, data: IJamData): Promise<void>;
+}): Promise<void>;
+/**
+ * Opens a Jam recorder window for the given recording ID or data.
+ *
+ * @param init - Recording ID string, data object, or URLSearchParams
+ * @param ses - Optional session (defaults to defaultSession from initialize)
+ * @returns The recorder BrowserWindow
+ *
+ * @example
+ * ```typescript
+ * import * as jam from '@jam.dev/recording-links/electron';
+ *
+ * // Open by recording ID
+ * jam.openRecorder('abc123');
+ *
+ * // Open with title
+ * jam.openRecorder({ recordingId: 'abc123', title: 'Bug Report' });
+ *
+ * // Open with URLSearchParams (from protocol handler)
+ * const params = new URLSearchParams('jam-recording=abc123&jam-title=Bug+Report');
+ * jam.openRecorder(params);
+ * ```
+ */
+export declare function openRecorder(init: string | JamData | ConstructorParameters<typeof JamData>[0], ses?: Session): BrowserWindow;
+/**
+ * Syntactic sugar for opening the recorder from a URL.
+ * Returns a tuple of the un-jammed URL and the recorder window, if opened.
+ */
+export declare function openUrl(url: string | URL, ses?: Session): [string, BrowserWindow | null];
+/**
+ * Data structure representing Jam recording parameters.
+ */
+export interface IJamData {
+    /** Jam recording ID */
+    readonly recordingId: string;
+    /** Optional recording title */
+    readonly title: string | undefined | null;
+    /**
+     * URLSearchParams containing jam-* query parameters.
+     * Follows the same convention as URL.searchParams.
+     */
+    readonly searchParams: URLSearchParams;
+    /**
+     * Query string with leading '?' (or empty string if no params).
+     * Follows the same convention as URL.search - includes the '?' prefix when params exist.
+     */
+    readonly search: string;
+}
+declare class JamData implements IJamData {
+    readonly recordingId: string;
+    readonly title: string | undefined | null;
+    get searchParams(): URLSearchParams;
+    get search(): string;
+    constructor(init: URLSearchParams | {
+        recordingId: string;
+        title?: string | null;
+    });
+}
+export declare function isJamRecorder(win: BrowserWindow | null): boolean;
+export declare function handleDisplayMediaRequest(sources: DesktopCapturerSource[], callback: DisplayMediaRequestHandlerCallback, requester?: BrowserWindow | null): void;
+export {};
+//# sourceMappingURL=electron.d.ts.map

package/lib/electron.js

@@ -0,0 +1 @@
+import{app as e,session as r,webContents as t,BrowserWindow as n,desktopCapturer as o}from"electron";const s={defaultSession:null,windows:new Map,openRecorderWindow(){throw new Error("Not initialized")},loadRecorderPage(){throw new Error("Not initialized")}},i=(e,r)=>{const s=e.frame,i=s?t.fromFrame(s):null,a=i?n.fromWebContents(i):null;u(a)?o.getSources({types:["screen","window"]}).then(e=>f(e,r,a)).catch(e=>{r({})}):r({})};async function a(t){if(!e.isReady())return e.whenReady().then(()=>a(t));const{defaultSession:n=r.defaultSession,defaultDisplayMediaRequestHandler:o=i}=t;s.defaultSession=n,s.openRecorderWindow=t.openRecorderWindow,s.loadRecorderPage=t.loadRecorderPage,o&&n.setDisplayMediaRequestHandler(o,{useSystemPicker:!0})}function d(e,r){const t=r??s.defaultSession;if(null===t)throw new Error("Cannot open recorder: no `session` found or provided");let n=s.windows.get(t);n||(n=s.openRecorderWindow(t),s.windows.set(t,n),n.on("closed",()=>s.windows.delete(t)));const o="string"==typeof e?new l({recordingId:e}):e instanceof l?e:new l(e);return s.loadRecorderPage(n,o).catch(e=>{}),n.isMinimized()&&n.restore(),n.focus(),n}function c(e,r){const t="string"==typeof e?new URL(e):e,n=new URLSearchParams;for(const[e,r]of t.searchParams.entries())e.startsWith("jam-")&&(n.set(e,r),t.searchParams.delete(e));return[t.href,n.has("jam-recording")?d(new l(n),r):null]}class l{get searchParams(){const e=new URLSearchParams;return e.set("jam-recording",this.recordingId),this.title&&e.set("jam-title",this.title),e}get search(){const e=this.searchParams.toString();return e?`?${e}`:""}constructor(e){if(e instanceof URLSearchParams){const r=e.get("jam-recording");if(!r)throw new Error("Missing jam-recording parameter");this.recordingId=r,this.title=e.get("jam-title")}else this.recordingId=e.recordingId,this.title=e.title||null}}function u(e){for(const r of s.windows.values())if(r===e)return!0;return!1}function f(e,r,t){const n=t?.getMediaSourceId(),o=e.filter(e=>!e.name.includes("DevTools")&&e.id!==n),s=o.find(e=>e.id.startsWith("window:")),i=o.find(e=>e.id.startsWith("screen:")),a=s||i||o[0];r(a?{video:a,audio:"loopback"}:{})}export{f as handleDisplayMediaRequest,a as initialize,u as isJamRecorder,d as openRecorder,c as openUrl};//# sourceMappingURL=electron.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jam.dev/recording-links",
-  "version": "0.2.0",
+  "version": "0.3.0-electron.5",
   "description": "Capture bug reports from your users with the Jam recording links SDK",
   "keywords": [
     "jam",
@@ -29,6 +29,10 @@
     "./lib/sdk": {
       "types": "./lib/sdk.d.ts",
       "import": "./lib/sdk.js"
+    },
+    "./electron": {
+      "types": "./lib/electron.d.ts",
+      "import": "./lib/electron.js"
     }
   },
   "files": [
@@ -63,5 +67,8 @@
     "tslib": "^2.8.1",
     "typescript": "^5.8.2",
     "vitest": "^2.1.8"
+  },
+  "optionalDependencies": {
+    "electron": "^39.2.3"
   }
 }