@jam.dev/recording-links 0.1.1 → 0.2.0

package/README.md

@@ -56,6 +56,7 @@ jam.initialize(); // Automatically loads recorder and opens recording "abc123"
 jam.initialize({
   teamId: "team-123,team-456", // Manually provide team ID(s); default: reads `<meta name="jam:team">` from the page
   openImmediately: false, // Don't auto-open recorder from URL params
+  //           OR: "recording-123" to auto-open a recording by ID
   parseJamData: (href) => {
     // Custom logic to extract recording data from URL
     const url = new URL(href);
@@ -93,7 +94,7 @@ Initializes the SDK with optional configuration.
 
 **Parameters:**
 - `options.teamId?: string` - Team ID for recording validation
-- `options.openImmediately?: boolean` - Whether to auto-open from URL (default: `true`)
+- `options.openImmediately?: boolean | string` - Whether to auto-open from URL (default: `true`), or a recording ID string to open immediately
 - `options.parseJamData?: (input: string) => SerializableJamData | null` - Custom URL parser
 - `options.applyJamData?: (data: SerializableJamData) => string` - Custom URL applier
 - `options.recorderRefCounter?: RefCounter` - Custom reference counter (advanced)
@@ -106,8 +107,7 @@ Initializes the SDK with optional configuration.
 Loads the Jam recorder module and returns a promise that resolves to the recorder interface.
 
 **Parameters:**
-- `options.recordingId?: string` - Recording ID to open immediately
-- Plus all options from `InitializeOptions`
+- `Omit<InitializeOptions, "recorderRefCounter">`
 
 **Returns:**
 - `Promise<RecorderSingleton>` - The Recorder singleton
@@ -115,6 +115,13 @@ Loads the Jam recorder module and returns a promise that resolves to the recorde
 **Throws:**
 - Error if SDK is not initialized
 
+### `isInitialized()`
+
+Returns whether the SDK has been initialized.
+
+**Returns:**
+- `boolean` - True if the SDK has been initialized, false otherwise
+
 ### `addEventListener(type, listener, options?)`
 
 Add an event listener for SDK events.
@@ -159,7 +166,7 @@ type SerializableJamData = {
 ```typescript
 type InitializeOptions = {
   teamId?: string;
-  openImmediately?: boolean;
+  openImmediately?: boolean | string | undefined | null;
   parseJamData?(input: string): SerializableJamData | null;
   applyJamData?(data: SerializableJamData): string;
   recorderRefCounter?: RefCounter;

package/lib/__tests__/helpers/browser-mocks.d.ts

@@ -0,0 +1,79 @@
+import { vi } from "vitest";
+/**
+ * Shared browser mocking utilities for consistent test environment setup.
+ * This consolidates duplicate browser mock implementations across test files.
+ */
+export interface MockLocalStorage {
+    getItem: ReturnType<typeof vi.fn>;
+    setItem: ReturnType<typeof vi.fn>;
+    removeItem: ReturnType<typeof vi.fn>;
+    clear: ReturnType<typeof vi.fn>;
+    length: number;
+    key: ReturnType<typeof vi.fn>;
+    _store: Record<string, string>;
+}
+export declare const createMockLocalStorage: () => MockLocalStorage;
+export interface MockHistory {
+    pushState: ReturnType<typeof vi.fn>;
+    replaceState: ReturnType<typeof vi.fn>;
+}
+export declare const createMockHistory: () => MockHistory;
+export interface MockWindow {
+    localStorage: MockLocalStorage;
+    location: {
+        href: string;
+    };
+    addEventListener: ReturnType<typeof vi.fn>;
+    removeEventListener: ReturnType<typeof vi.fn>;
+    history: MockHistory;
+}
+export declare const createMockWindow: (initialUrl?: string) => MockWindow;
+export declare class MockPopStateEvent {
+    type: string;
+    constructor(type: string, options?: PopStateEventInit);
+    state: any;
+}
+export declare class MockCustomEvent {
+    type: string;
+    options: {
+        detail?: any;
+    };
+    constructor(type: string, options?: {
+        detail?: any;
+    });
+    detail: any;
+}
+export declare class MockEventTarget {
+    private listeners;
+    addEventListener(type: string, listener: EventListener, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListener, options?: boolean | AddEventListenerOptions): void;
+    dispatchEvent(event: CustomEvent): boolean;
+}
+/**
+ * Complete browser environment mock setup
+ */
+export interface BrowserMocks {
+    localStorage: MockLocalStorage;
+    window: MockWindow;
+    history: MockHistory;
+    resetMocks: () => void;
+}
+export declare const createBrowserMocks: (initialUrl?: string) => BrowserMocks;
+/**
+ * Helper to set test URL with parameters
+ */
+export declare const setTestUrl: (params?: Record<string, string>, baseUrl?: string) => string;
+/**
+ * Helper to create mock RefCounter for tests
+ */
+export declare const createMockRefCounter: (count?: number) => {
+    count: number;
+    update: import("vitest").Mock<(...args: any[]) => any>;
+    addEventListener: import("vitest").Mock<(...args: any[]) => any>;
+    removeEventListener: import("vitest").Mock<(...args: any[]) => any>;
+};
+/**
+ * Browser environment setup helper that combines environment reset with mock creation
+ */
+export declare const setupBrowserEnvironment: (initialUrl?: string) => MockHistory;
+//# sourceMappingURL=browser-mocks.d.ts.map

package/lib/__tests__/setup.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=setup.d.ts.map

package/lib/sdk.d.ts

@@ -10,7 +10,7 @@ type Events = {
         name: "recorder";
         Recorder: RecorderSingleton;
     } | {
-        name: Exclude<ScriptName, "recorder">;
+        name: "capture";
     });
 };
 /**
@@ -48,9 +48,11 @@ type InitializeOptions = {
     teamId?: string;
     /**
      * Whether to open the JamRecorder immediately on initialization.
+     * May be provided a recording ID as a string, in which case we will open it.
+     * If the value resolves to `undefined` or `null`, we will default to `true`.
      * Default: `true`
      */
-    openImmediately?: boolean;
+    openImmediately?: boolean | string | undefined | null;
     /**
      * Extract a `recordingId` and `jamTitle` from the provided string.
      * Defaults to reading the `jam-recording` and `jam-title` QSPs off the URL.
@@ -62,6 +64,8 @@ type InitializeOptions = {
      * Setting a custom `parseJamData` disables this default.
      */
     applyJamData?(data: SerializableJamData): string;
+    /** Selectors to blur on host pages while the Jam Recorder is recording. */
+    blurSelectors?: string | string[] | (() => string | string[]);
 };
 /**
  * Data structure representing Jam recording metadata that can be serialized to/from URLs.
@@ -72,6 +76,9 @@ export type SerializableJamData = {
     /** The human-readable title of the recording, or null if not present */
     jamTitle: string | null;
 };
+declare function resetForTesting(): void;
+/** @internal - Reset SDK state for testing (only available in dev builds) */
+export declare const _resetForTesting: typeof resetForTesting | undefined;
 /**
  * Add an event listener for SDK events.
  * @param type - The event type to listen for
@@ -86,6 +93,8 @@ export declare const addEventListener: <K extends "loaded">(type: K, listener: (
  * @param options - Optional event listener configuration
  */
 export declare const removeEventListener: <K extends "loaded">(type: K, listener: (event: CustomEvent<Events[K]>) => void, options?: boolean | AddEventListenerOptions) => void;
+/** Whether the SDK has been initialized. */
+export declare const isInitialized: () => false;
 /**
  * The loaded Recorder singleton instance. Will be null until loadRecorder() is called successfully.
  */
@@ -101,6 +110,7 @@ export declare let Recorder: RecorderSingleton | null;
  * @param options.recorderRefCounter - Custom reference counter for managing recorder instances across tabs
  * @param options.teamId - Team ID for validating recording IDs
  * @param options.openImmediately - Whether to automatically open recorder from URL parameters (default: true)
+ *                                  Can be set to a specific recording ID as a string to open that recording.
  * @param options.parseJamData - Custom function to extract recording data from URLs
  * @param options.applyJamData - Custom function to apply recording data to URLs
  *
@@ -114,11 +124,11 @@ export declare let Recorder: RecorderSingleton | null;
  * // Custom configuration
  * jam.initialize({
  *   teamId: "team-123",
- *   openImmediately: false
+ *   openImmediately: false // or "abc-123" to open a specific recording
  * });
  * ```
  */
-export declare function initialize({ recorderRefCounter, ...config }?: InitializeOptions): void;
+export declare function initialize({ recorderRefCounter, _loadRemoteScript, ...config }?: InitializeOptions): void;
 /**
  * Loads the Jam recorder module and returns the recorder singleton.
  *
@@ -127,9 +137,9 @@ export declare function initialize({ recorderRefCounter, ...config }?: Initializ
  * for cross-tab coordination.
  *
  * @param options - Configuration options for loading the recorder
- * @param options.recordingId - Optional recording ID to open immediately after loading
  * @param options.teamId - Team ID for validating recording IDs
  * @param options.openImmediately - Whether to automatically open the recorder (default: true)
+ *                                  Can be set to a specific recording ID as a string to open that recording.
  * @param options.parseJamData - Custom function to extract recording data from URLs
  * @param options.applyJamData - Custom function to apply recording data to URLs
  *
@@ -145,18 +155,13 @@ export declare function initialize({ recorderRefCounter, ...config }?: Initializ
  *
  * // Load recorder and open a specific recording
  * const recorder = await jam.loadRecorder({
- *   recordingId: "recording-abc123"
+ *   openImmediately: false, // or "recording-abc123"
  * });
  *
  * // Use the recorder
  * recorder.open("recording-xyz789", { jamTitle: "Bug Report" });
  * ```
  */
-export declare function loadRecorder({ recordingId, ...config }?: Omit<InitializeOptions, "recorderRefCounter"> & {
-    /**
-     * An optional recording ID; if provided, a recorder will to open the recorder with.
-     */
-    recordingId?: string | null;
-}): Promise<RecorderSingleton>;
+export declare function loadRecorder({ ...config }?: Omit<InitializeOptions, "recorderRefCounter">): Promise<RecorderSingleton>;
 export {};
 //# sourceMappingURL=sdk.d.ts.map

package/lib/sdk.js

@@ -1,5 +1,5 @@
-function e(){const e=new EventTarget;return{addEventListener(t,r,n){e.addEventListener(t,r,n)},removeEventListener(t,r,n){e.removeEventListener(t,r,n)},dispatch:(t,r)=>e.dispatchEvent(new CustomEvent(t,{detail:r}))}}const t=t=>{const r=`jam:${t}`,n=e();let i=Number.parseInt(localStorage.getItem(r)??"0",10)||0;return window.addEventListener("storage",e=>{if(e.storageArea===localStorage&&e.key===r){const t=Number.parseInt(e.newValue??"",10);Number.isNaN(t)||t===i||(i=t,n.dispatch("update",i))}}),{count:i,addEventListener:n.addEventListener.bind(n),removeEventListener:n.removeEventListener.bind(n),update(e){const t=i;switch(e){case"increment":i+=1;break;case"decrement":i-=1;break;default:i=e}return i<0&&(i=0),i!==t&&(localStorage.setItem(r,`${i}`),n.dispatch("update",i)),i}}},r=e=>{try{const t=new URL(e);return{recordingId:t.searchParams.get("jam-recording"),jamTitle:t.searchParams.get("jam-title")}}catch(e){}return null},n={isInitialized:!1},i=e(),a=i.addEventListener.bind(i),o=i.removeEventListener.bind(i);let d=null;function c({recorderRefCounter:e=t("numRecorders"),...i}={}){if(n.isInitialized)throw new Error("SDK already initialized.");Object.assign(n,{isInitialized:!0,recorderRefCounter:e,config:i}),e.count>0?u("capture"):e.addEventListener("update",()=>u("capture"),{once:!0}),window.addEventListener("popstate",o);const a={apply(e,t,r){const n=Reflect.apply(e,t,r);return o(),n}};function o(){if(d)return;const e=n.config?.parseJamData??r,t=e(window.location.href)?.recordingId;t&&s({recordingId:t})}history.pushState=new Proxy(history.pushState,a),history.replaceState=new Proxy(history.replaceState,a),o()}async function s({recordingId:e,...t}={}){if(d)return d;if(!n.isInitialized)throw new Error("SDK not initialized. Call initialize() first.");if(({Recorder:d}=await u("recorder")),!d)throw new Error("Failed to load recorder script.");const{openImmediately:r,...i}={...n.config,...t};return d.initialize({...i,openImmediately:!e&&r}),n.recorderRefCounter.update("increment"),window.addEventListener("pagehide",()=>{n.recorderRefCounter.update("decrement")}),e&&!1!==r&&d.open(e,i),d}async function u(e){const t=`https://js.jam.dev/${e}.js`,r=await import(
+function e(){const e=new EventTarget;return{addEventListener(t,n,r){e.addEventListener(t,n,r)},removeEventListener(t,n,r){e.removeEventListener(t,n,r)},dispatch:(t,n)=>e.dispatchEvent(new CustomEvent(t,{detail:n}))}}const t=(t,n=localStorage)=>{const r=`jam:${t}`,i=e();let o=null;try{o=n.getItem(r)}catch(e){}const a={count:Number.parseInt(o??"0",10)||0,addEventListener:i.addEventListener.bind(i),removeEventListener:i.removeEventListener.bind(i),update(e){const t=a.count;switch(e){case"increment":a.count+=1;break;case"decrement":a.count-=1;break;default:a.count=e}if(a.count<0&&(a.count=0),a.count!==t){try{n.setItem(r,`${a.count}`)}catch(e){}Object.assign(a,{count:a.count}),i.dispatch("update",a.count)}return a.count}};return window.addEventListener("storage",e=>{if(e.storageArea===n&&e.key===r){const t=Number.parseInt(e.newValue??"",10);Number.isNaN(t)||t===a.count||(a.count=t,i.dispatch("update",a.count))}}),a},n=e=>{try{const t=new URL(e);return{recordingId:t.searchParams.get("jam-recording"),jamTitle:t.searchParams.get("jam-title")}}catch(e){}return null},r={isInitialized:!1},i=void 0,o=e(),a=o.addEventListener.bind(o),c=o.removeEventListener.bind(o),d=()=>r.isInitialized;let s=null;function u({recorderRefCounter:e=t("numRecorders"),_loadRemoteScript:i=m,...o}={}){if(r.isInitialized)throw new Error("SDK already initialized.");Object.assign(r,{isInitialized:!0,recorderRefCounter:e,config:o,_loadRemoteScript:i}),e.count>0?p():e.addEventListener("update",p,{once:!0}),window.addEventListener("popstate",c);const a={apply(e,t,n){const r=Reflect.apply(e,t,n);return c(),r}};function c(){if(s)return;const e=r.config?.parseJamData??n,t="string"==typeof r.config?.openImmediately?r.config.openImmediately:e(window.location.href)?.recordingId;t&&l({openImmediately:!1!==r.config?.openImmediately&&t})}history.pushState=new Proxy(history.pushState,a),history.replaceState=new Proxy(history.replaceState,a),c()}async function l({...e}={}){if(s)return s;if(!r.isInitialized)throw new Error("SDK not initialized. Call initialize() first.");if(({Recorder:s}=await r._loadRemoteScript("recorder")),!s)throw new Error("Failed to load recorder script.");const{openImmediately:t,...n}={...r.config,...e},i="string"==typeof t?t:null;return s.initialize({...n,openImmediately:!i&&(t??!0)}),r.recorderRefCounter.update("increment"),window.addEventListener("pagehide",()=>{r.recorderRefCounter.update("decrement")}),i&&s.open(i,n),s}async function p(){if(!r.isInitialized||!r._loadRemoteScript)throw new Error("SDK not initialized. Call initialize() first.");const{Capture:e}=await r._loadRemoteScript("capture")??{};await(e?.initialize(r.config))}async function m(e){const t=`https://js.jam.dev/${e}.js`,n=await import(
 /* webpackIgnore: true */
 /* @vite-ignore */
 /* @rollup/plugin-dynamic-import-vars ignore */
-t);if("recorder"===e){if(!r.Recorder)throw new Error("Loaded recorder script, but Recorder not found.");i.dispatch("loaded",{type:"script",name:e,Recorder:r.Recorder})}else i.dispatch("loaded",{type:"script",name:e});return r}export{d as Recorder,a as addEventListener,c as initialize,s as loadRecorder,o as removeEventListener};//# sourceMappingURL=sdk.js.map
+t);if("recorder"===e){if(!n.Recorder)throw new Error("Loaded recorder script, but Recorder not found.");o.dispatch("loaded",{type:"script",name:e,Recorder:n.Recorder})}else o.dispatch("loaded",{type:"script",name:e});return n}export{s as Recorder,i as _resetForTesting,a as addEventListener,u as initialize,d as isInitialized,l as loadRecorder,c as removeEventListener};//# sourceMappingURL=sdk.js.map

package/lib/utils/refs.d.ts

@@ -5,5 +5,5 @@ export type RefCounter = Omit<events.Emitter<{
     count: number;
     update(value: "increment" | "decrement" | number): number;
 };
-export declare const createLocalStorageRefCounter: <K extends string>(name: K) => RefCounter;
+export declare const createStorageRefCounter: <K extends string>(name: K, storage?: Storage) => RefCounter;
 //# sourceMappingURL=refs.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jam.dev/recording-links",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Capture bug reports from your users with the Jam recording links SDK",
   "keywords": [
     "jam",
@@ -25,6 +25,10 @@
     "./sdk": {
       "types": "./lib/sdk.d.ts",
       "import": "./lib/sdk.js"
+    },
+    "./lib/sdk": {
+      "types": "./lib/sdk.d.ts",
+      "import": "./lib/sdk.js"
     }
   },
   "files": [
@@ -39,11 +43,11 @@
     "dev:remote": "rollup -c --watch --environment BUILD:dev,JAM_JS_ORIGIN:prod",
     "dev:staging": "rollup -c --watch --environment BUILD:dev,JAM_JS_ORIGIN:staging",
     "build": "rollup -c --environment BUILD:prod",
-    "prepublishOnly": "bun run scripts/validate-build.ts",
     "build:dev": "rollup -c --environment BUILD:dev",
+    "prepublishOnly": "bun run scripts/validate-build.ts",
     "lint": "biome lint './src' --diagnostic-level=error",
     "lint:fix": "biome lint './src' --diagnostic-level=error --fix",
-    "test": "vitest --passWithNoTests",
+    "test": "vitest --passWithNoTests src/",
     "type-check": "tsc --noEmit"
   },
   "dependencies": {},
@@ -54,6 +58,7 @@
     "@rollup/plugin-typescript": "^11.1.6",
     "@types/node": "^20.0.0",
     "biome": "^0.3.3",
+    "jsdom": "^27.0.0",
     "rollup": "^4.12.0",
     "tslib": "^2.8.1",
     "typescript": "^5.8.2",