feat(raycast): add Cap.so Raycast extension (#28)

apps/raycast-extension/README.md

@@ -0,0 +1,9 @@
+# Cap.so Raycast Extension
+
+Control [Cap](https://cap.so) screen recordings and open your web dashboard directly from Raycast.
+
+## Commands
+
+- **Start Recording** (`start-recording`): Starts a Cap screen recording using your configured default recording mode (`instant` or `studio`), target screen, camera, microphone, and system audio settings via `cap-desktop://action?value=...`.
+- **Stop Recording** (`stop-recording`): Stops the active Cap recording via `cap-desktop://action?value=%22stop_recording%22` and preserves/copies the shareable Cap video link (`https://cap.so/s/...`) to your clipboard by default.
+- **Open Web Dashboard** (`open-dashboard`): Opens `https://cap.so/dashboard` (or your custom self-hosted Cap Web URL) in your default browser.

apps/raycast-extension/package.json

@@ -0,0 +1,116 @@
+{
+	"$schema": "https://www.raycast.com/schemas/extension.json",
+	"name": "@cap/raycast-extension",
+	"title": "Cap Screen Recorder",
+	"description": "Start and stop Cap recordings and open your Cap web dashboard directly from Raycast.",
+	"icon": "extension-icon.png",
+	"author": "capsoftware",
+	"categories": ["Productivity", "Media", "Developer Tools"],
+	"license": "MIT",
+	"preferences": [
+		{
+			"name": "defaultMode",
+			"title": "Default Recording Mode",
+			"description": "Recording mode used when starting a recording from Raycast.",
+			"type": "dropdown",
+			"required": false,
+			"default": "instant",
+			"data": [
+				{
+					"title": "Instant Mode",
+					"value": "instant"
+				},
+				{
+					"title": "Studio Mode",
+					"value": "studio"
+				}
+			]
+		},
+		{
+			"name": "defaultScreen",
+			"title": "Default Screen Name",
+			"description": "Exact display name of the screen to capture (leave empty to detect the active macOS display).",
+			"type": "textfield",
+			"required": false,
+			"default": ""
+		},
+		{
+			"name": "cameraDeviceId",
+			"title": "Camera Device ID",
+			"description": "Optional camera device identifier to enable during recording.",
+			"type": "textfield",
+			"required": false,
+			"default": ""
+		},
+		{
+			"name": "micLabel",
+			"title": "Microphone Name",
+			"description": "Optional microphone display name to capture audio from.",
+			"type": "textfield",
+			"required": false,
+			"default": ""
+		},
+		{
+			"name": "captureSystemAudio",
+			"title": "Capture System Audio",
+			"description": "Include system audio when starting a recording.",
+			"type": "checkbox",
+			"label": "Capture system audio by default",
+			"required": false,
+			"default": true
+		},
+		{
+			"name": "copyUrlOnStop",
+			"title": "Copy Video URL on Stop",
+			"description": "Copy the shareable Cap video URL to the clipboard when stopping a recording.",
+			"type": "checkbox",
+			"label": "Copy shareable URL automatically",
+			"required": false,
+			"default": true
+		},
+		{
+			"name": "dashboardUrl",
+			"title": "Cap Dashboard URL",
+			"description": "URL of your Cap web dashboard (supports Cap Cloud and self-hosted instances).",
+			"type": "textfield",
+			"required": false,
+			"default": "https://cap.so/dashboard"
+		}
+	],
+	"commands": [
+		{
+			"name": "start-recording",
+			"title": "Start Recording",
+			"description": "Start a Cap recording using your configured default settings.",
+			"mode": "no-view"
+		},
+		{
+			"name": "stop-recording",
+			"title": "Stop Recording",
+			"description": "Stop the active Cap recording and copy the video URL to your clipboard.",
+			"mode": "no-view"
+		},
+		{
+			"name": "open-dashboard",
+			"title": "Open Web Dashboard",
+			"description": "Open the Cap web dashboard in your default browser.",
+			"mode": "no-view"
+		}
+	],
+	"dependencies": {
+		"@raycast/api": "^1.83.1"
+	},
+	"devDependencies": {
+		"@types/node": "^20.11.5",
+		"typescript": "^5.8.3",
+		"vitest": "^3.2.0"
+	},
+	"scripts": {
+		"build": "ray build -e dist",
+		"dev": "ray develop",
+		"lint": "ray lint",
+		"fix-lint": "ray lint --fix",
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"test": "vitest run"
+	}
+}

apps/raycast-extension/src/deeplink.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import {
+	type StartRecordingPreferences,
+	buildStartRecordingDeepLink,
+	buildStartRecordingPayload,
+	buildStopRecordingDeepLink,
+	extractShareableCapUrl,
+	parseUnambiguousDisplayFromSystemProfiler,
+	resolveDashboardUrl,
+} from "./deeplink";
+
+describe("Cap Raycast deep-link builders", () => {
+	it("constructs start_recording payloads preserving mode, screen, devices, and audio", () => {
+		const prefs: StartRecordingPreferences = {
+			defaultMode: "studio",
+			defaultScreen: "Built-in Retina Display",
+			cameraDeviceId: "cam-01",
+			micLabel: "Studio Mic",
+			captureSystemAudio: false,
+		};
+		const payload = buildStartRecordingPayload(prefs);
+
+		expect(payload).toEqual({
+			start_recording: {
+				capture_mode: { screen: "Built-in Retina Display" },
+				camera: { DeviceID: "cam-01" },
+				mic_label: "Studio Mic",
+				capture_system_audio: false,
+				mode: "studio",
+			},
+		});
+
+		const url = new URL(buildStartRecordingDeepLink(prefs));
+		expect(url.protocol).toBe("cap-desktop:");
+		expect(url.host).toBe("action");
+		const decoded = JSON.parse(url.searchParams.get("value") || "{}");
+		expect(decoded).toEqual(payload);
+	});
+
+	it("falls back to detected macOS display name or throws when none is available", () => {
+		const payload = buildStartRecordingPayload({}, () => "Studio Display");
+		expect(payload.start_recording.capture_mode).toEqual({
+			screen: "Studio Display",
+		});
+		expect(() => buildStartRecordingPayload({}, () => null)).toThrow(
+			/No target screen name/,
+		);
+
+		const singleDisplayJson = JSON.stringify({
+			SPDisplaysDataType: [
+				{ spdisplays_ndrvs: [{ _name: "Built-in Retina Display" }] },
+			],
+		});
+		expect(parseUnambiguousDisplayFromSystemProfiler(singleDisplayJson)).toBe(
+			"Built-in Retina Display",
+		);
+
+		const multiDisplayJson = JSON.stringify({
+			SPDisplaysDataType: [
+				{
+					spdisplays_ndrvs: [
+						{ _name: "Built-in Retina Display" },
+						{ _name: "Studio Display" },
+					],
+				},
+			],
+		});
+		expect(
+			parseUnambiguousDisplayFromSystemProfiler(multiDisplayJson),
+		).toBeNull();
+	});
+
+	it("encodes stop_recording and resolves dashboard and share URLs", () => {
+		const stopUrl = new URL(buildStopRecordingDeepLink());
+		expect(stopUrl.searchParams.get("value")).toBe('"stop_recording"');
+
+		expect(resolveDashboardUrl()).toBe("https://cap.so/dashboard");
+		expect(resolveDashboardUrl("https://cap.internal.local/dashboard/")).toBe(
+			"https://cap.internal.local/dashboard",
+		);
+
+		expect(extractShareableCapUrl("https://cap.so/s/abc123xyz")).toBe(
+			"https://cap.so/s/abc123xyz",
+		);
+		expect(extractShareableCapUrl("not a link")).toBeNull();
+	});
+});

apps/raycast-extension/src/deeplink.ts

@@ -0,0 +1,182 @@
+import { execFileSync } from "node:child_process";
+
+export type RecordingMode = "instant" | "studio";
+
+export interface StartRecordingPreferences {
+	defaultMode?: RecordingMode;
+	defaultScreen?: string;
+	cameraDeviceId?: string;
+	micLabel?: string;
+	captureSystemAudio?: boolean;
+}
+
+export interface StopRecordingPreferences {
+	copyUrlOnStop?: boolean;
+	dashboardUrl?: string;
+}
+
+export interface DeepLinkStartPayload {
+	start_recording: {
+		capture_mode: { screen: string } | { window: string };
+		camera: { DeviceID: string } | null;
+		mic_label: string | null;
+		capture_system_audio: boolean;
+		mode: RecordingMode;
+	};
+}
+
+const CAP_ACTION_BASE_URL = "cap-desktop://action";
+const DEFAULT_DASHBOARD_URL = "https://cap.so/dashboard";
+const ACTIVE_SCREEN_JXA_SCRIPT = [
+	'ObjC.import("AppKit");',
+	"const mouse = $.NSEvent.mouseLocation;",
+	"const screens = $.NSScreen.screens;",
+	"const count = screens.count;",
+	"let chosen = null;",
+	"for (let i = 0; i < count; i++) {",
+	"  const s = screens.objectAtIndex(i);",
+	"  const f = s.frame;",
+	"  if (mouse.x >= f.origin.x && mouse.x <= f.origin.x + f.size.width && mouse.y >= f.origin.y && mouse.y <= f.origin.y + f.size.height) {",
+	"    chosen = s;",
+	"    break;",
+	"  }",
+	"}",
+	"if (!chosen) { chosen = $.NSScreen.mainScreen; }",
+	'chosen ? ObjC.unwrap(chosen.localizedName) : "";',
+].join(" ");
+
+export function parseUnambiguousDisplayFromSystemProfiler(
+	rawJson: string,
+): string | null {
+	try {
+		const parsed = JSON.parse(rawJson) as {
+			SPDisplaysDataType?: Array<{
+				spdisplays_ndrvs?: Array<{ _name?: string }>;
+			}>;
+		};
+		const names: string[] = [];
+		for (const gpu of parsed.SPDisplaysDataType ?? []) {
+			for (const display of gpu.spdisplays_ndrvs ?? []) {
+				const name = display._name?.trim();
+				if (name) {
+					names.push(name);
+				}
+			}
+		}
+		return names.length === 1 ? names[0] : null;
+	} catch {
+		return null;
+	}
+}
+
+function queryActiveScreenViaAppKit(): string | null {
+	try {
+		const activeName = execFileSync(
+			"osascript",
+			["-l", "JavaScript", "-e", ACTIVE_SCREEN_JXA_SCRIPT],
+			{ encoding: "utf8", timeout: 2000 },
+		).trim();
+		return activeName || null;
+	} catch {
+		return null;
+	}
+}
+
+export function detectActiveMacDisplayName(): string | null {
+	const activeScreen = queryActiveScreenViaAppKit();
+	if (activeScreen) {
+		return activeScreen;
+	}
+
+	try {
+		const output = execFileSync(
+			"system_profiler",
+			["SPDisplaysDataType", "-json"],
+			{ encoding: "utf8", timeout: 3000 },
+		);
+		return parseUnambiguousDisplayFromSystemProfiler(output);
+	} catch {
+		return null;
+	}
+}
+
+export function resolveTargetScreenName(
+	prefs: StartRecordingPreferences,
+	detectDisplay: () => string | null = detectActiveMacDisplayName,
+): string {
+	const configured = prefs.defaultScreen?.trim();
+	if (configured) {
+		return configured;
+	}
+	const detected = detectDisplay()?.trim();
+	if (detected) {
+		return detected;
+	}
+	throw new Error(
+		"No target screen name configured or detected. Set Default Screen Name in Raycast preferences.",
+	);
+}
+
+export function buildStartRecordingPayload(
+	prefs: StartRecordingPreferences,
+	detectDisplay: () => string | null = detectActiveMacDisplayName,
+): DeepLinkStartPayload {
+	const screenName = resolveTargetScreenName(prefs, detectDisplay);
+	const cameraId = prefs.cameraDeviceId?.trim();
+	const micName = prefs.micLabel?.trim();
+
+	return {
+		start_recording: {
+			capture_mode: { screen: screenName },
+			camera: cameraId ? { DeviceID: cameraId } : null,
+			mic_label: micName || null,
+			capture_system_audio: prefs.captureSystemAudio ?? true,
+			mode: prefs.defaultMode || "instant",
+		},
+	};
+}
+
+export function encodeCapActionUrl(actionValue: unknown): string {
+	const serialized = JSON.stringify(actionValue);
+	return `${CAP_ACTION_BASE_URL}?value=${encodeURIComponent(serialized)}`;
+}
+
+export function buildStartRecordingDeepLink(
+	prefs: StartRecordingPreferences = {},
+	detectDisplay: () => string | null = detectActiveMacDisplayName,
+): string {
+	return encodeCapActionUrl(buildStartRecordingPayload(prefs, detectDisplay));
+}
+
+export function buildStopRecordingDeepLink(): string {
+	return encodeCapActionUrl("stop_recording");
+}
+
+export function resolveDashboardUrl(customUrl?: string): string {
+	const trimmed = customUrl?.trim();
+	if (!trimmed) {
+		return DEFAULT_DASHBOARD_URL;
+	}
+	return trimmed.replace(/\/+$/, "");
+}
+
+export function extractShareableCapUrl(
+	clipboardText: string | undefined,
+	dashboardBaseUrl?: string,
+): string | null {
+	if (!clipboardText) {
+		return null;
+	}
+	const trimmed = clipboardText.trim();
+	const customOrigin = resolveDashboardUrl(dashboardBaseUrl).replace(
+		/\/dashboard$/,
+		"",
+	);
+	const isCapLink =
+		trimmed.startsWith("https://cap.so/s/") ||
+		trimmed.startsWith("https://cap.link/") ||
+		(customOrigin.startsWith("http") &&
+			trimmed.startsWith(`${customOrigin}/s/`));
+
+	return isCapLink ? trimmed : null;
+}