@opentray/spec 0.0.0 → 0.2.0

package/README.md

@@ -5,7 +5,26 @@ Shared TypeScript protocol and contract package for OpenTray.
 ## Role
 
 - Define JSON-RPC payload shapes.
+- Define broker protocol version and endpoint identity helpers.
 - Define public `Surface`, `Tray`, `Lease`, and extension contract types.
 - Keep protocol types reusable by the `opentray` package and official extensions.
 
 This package must stay platform-neutral and must not import native implementation packages.
+
+## Example
+
+Run a protocol parser example that shows successful server-frame parsing and malformed-frame rejection:
+
+```bash
+pnpm --filter @opentray/spec example:parse
+```
+
+Endpoint identity is version-scoped during the current unstable broker stage:
+
+```ts
+import { createBrokerEndpointIdentity, formatUnixSocketPath } from "@opentray/spec";
+
+const identity = createBrokerEndpointIdentity({ packageVersion: "0.1.0" });
+console.log(formatUnixSocketPath("~", identity));
+// ~/.opentray/0.1.0/opentray-p1.sock
+```

package/dist/index.d.mts

@@ -0,0 +1,251 @@
+//#region src/index.d.ts
+type LeaseId = string;
+type RequestId = string;
+type SurfaceId = string;
+type TrayId = string;
+type MenuItemId = number;
+declare const PROTOCOL_VERSION = 1;
+interface BrokerEndpointIdentity {
+  packageVersion: string;
+  protocolVersion: number;
+}
+interface BrokerEndpointIdentityOptions {
+  packageVersion: string;
+  protocolVersion?: number;
+}
+declare const createBrokerEndpointIdentity: ({
+  packageVersion,
+  protocolVersion
+}: BrokerEndpointIdentityOptions) => BrokerEndpointIdentity;
+declare const isSupportedProtocolVersion: (protocolVersion: number) => boolean;
+declare const formatBrokerEndpointName: (identity: BrokerEndpointIdentity) => string;
+declare const formatBrokerStateRoot: (homeDir: string, identity: BrokerEndpointIdentity) => string;
+declare const formatUnixSocketPath: (homeDir: string, identity: BrokerEndpointIdentity) => string;
+declare const formatWindowsPipeName: (identity: BrokerEndpointIdentity) => string;
+interface SurfaceOptions {
+  appId: string;
+  title?: string;
+  icon?: Icon;
+  default?: boolean;
+}
+interface SurfaceRef {
+  surfaceId: SurfaceId;
+  appId: string;
+}
+interface TrayOptions {
+  trayId?: TrayId;
+  appId?: string;
+  title?: string;
+  tooltip?: Tooltip;
+  icon: Icon;
+  menu?: Menu;
+}
+interface Tooltip {
+  title: string;
+  description: string;
+}
+interface Menu {
+  items: MenuItem[];
+}
+type MenuItem = {
+  type: "item";
+  id: MenuItemId;
+  title: string;
+  enabled?: boolean;
+  shortcut?: string;
+} | {
+  type: "check";
+  id: MenuItemId;
+  title: string;
+  enabled?: boolean;
+  checked?: boolean;
+} | {
+  type: "radio";
+  id: MenuItemId;
+  title: string;
+  enabled?: boolean;
+  checked?: boolean;
+  group: number;
+} | {
+  type: "separator";
+} | {
+  type: "submenu";
+  title: string;
+  enabled?: boolean;
+  items: MenuItem[];
+};
+type Icon = {
+  type: "rgba";
+  data: Uint8Array | number[];
+  width: number;
+  height: number;
+} | {
+  type: "encoded";
+  data: Uint8Array | number[];
+} | {
+  type: "file";
+  path: string;
+};
+interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+type MouseButton = "left" | "right" | "middle";
+type TrayEvent = {
+  type: "ready";
+  surfaceId: SurfaceId;
+} | {
+  type: "menuClick";
+  surfaceId: SurfaceId;
+  trayId: TrayId;
+  itemId: MenuItemId;
+} | {
+  type: "trayClick";
+  surfaceId: SurfaceId;
+  button: MouseButton;
+  x: number;
+  y: number;
+} | {
+  type: "trayDoubleClick";
+  surfaceId: SurfaceId;
+  button: MouseButton;
+  x: number;
+  y: number;
+};
+interface ExtensionScope {
+  surfaceId: SurfaceId;
+  trayId?: TrayId;
+  ext: string;
+}
+interface ExtensionEnvelope<TData = unknown> {
+  scope: ExtensionScope;
+  data: TData;
+}
+interface DaemonSessionHealth {
+  sessionId: number;
+  leaseId?: LeaseId;
+  initialized: boolean;
+}
+interface DaemonHealth {
+  pid: number;
+  packageVersion: string;
+  protocolVersion: number;
+  endpoint: string;
+  sessionCount: number;
+  sessions: DaemonSessionHealth[];
+}
+type ClientFrame = {
+  type: "init";
+  protocolVersion: number;
+  clientVersion: string;
+} | ClientRequestFrame | {
+  type: "exit";
+};
+type ClientRequestFrame = ({
+  type: "create-surface";
+  requestId: RequestId;
+} & SurfaceOptions) | {
+  type: "resolve-default-surface";
+  requestId: RequestId;
+} | {
+  type: "create-tray";
+  requestId: RequestId;
+  surface: SurfaceRef;
+  tray: TrayOptions;
+} | {
+  type: "destroy-tray";
+  requestId: RequestId;
+  surfaceId: SurfaceId;
+  trayId: TrayId;
+} | {
+  type: "set-tray-menu";
+  requestId: RequestId;
+  surfaceId: SurfaceId;
+  trayId: TrayId;
+  menu: Menu;
+} | {
+  type: "set-tray-icon";
+  requestId: RequestId;
+  surfaceId: SurfaceId;
+  trayId: TrayId;
+  icon: Icon;
+} | {
+  type: "set-tray-tooltip";
+  requestId: RequestId;
+  surfaceId: SurfaceId;
+  trayId: TrayId;
+  tooltip: Tooltip;
+} | {
+  type: "load-ext";
+  requestId: RequestId;
+  surfaceId: SurfaceId;
+  name: string;
+  path: string;
+} | {
+  type: "ext-command";
+  requestId: RequestId;
+  surfaceId: SurfaceId;
+  trayId: TrayId;
+  ext: string;
+  data: unknown;
+} | {
+  type: "unload-ext";
+  requestId: RequestId;
+  surfaceId: SurfaceId;
+  name: string;
+} | {
+  type: "health";
+  requestId: RequestId;
+};
+type ServerFrame = {
+  type: "ready";
+  protocolVersion: number;
+  brokerVersion: string;
+  leaseId: LeaseId;
+} | {
+  type: "surface-created";
+  requestId: RequestId;
+  surface: SurfaceRef;
+} | {
+  type: "default-surface";
+  requestId: RequestId;
+  surface: SurfaceRef;
+} | {
+  type: "tray-created";
+  requestId: RequestId;
+  surfaceId: SurfaceId;
+  trayId: TrayId;
+} | {
+  type: "ack";
+  requestId: RequestId;
+} | {
+  type: "daemon-health";
+  requestId: RequestId;
+  health: DaemonHealth;
+} | {
+  type: "event";
+  event: TrayEvent;
+} | {
+  type: "ext-event";
+  surfaceId: SurfaceId;
+  trayId: TrayId;
+  ext: string;
+  data: unknown;
+} | {
+  type: "error";
+  requestId?: RequestId;
+  code: string;
+  message: string;
+};
+interface ParseResult<T> {
+  ok: boolean;
+  frame?: T;
+  error?: string;
+}
+declare const parseServerFrame: (line: string) => ParseResult<ServerFrame>;
+declare const isServerFrame: (value: unknown) => value is ServerFrame;
+//#endregion
+export { BrokerEndpointIdentity, BrokerEndpointIdentityOptions, ClientFrame, ClientRequestFrame, DaemonHealth, DaemonSessionHealth, ExtensionEnvelope, ExtensionScope, Icon, LeaseId, Menu, MenuItem, MenuItemId, MouseButton, PROTOCOL_VERSION, ParseResult, Rect, RequestId, ServerFrame, SurfaceId, SurfaceOptions, SurfaceRef, Tooltip, TrayEvent, TrayId, TrayOptions, createBrokerEndpointIdentity, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isServerFrame, isSupportedProtocolVersion, parseServerFrame };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -0,0 +1,85 @@
+//#region src/index.ts
+const PROTOCOL_VERSION = 1;
+const createBrokerEndpointIdentity = ({ packageVersion, protocolVersion = 1 }) => {
+	assertEndpointComponent(packageVersion, "packageVersion");
+	if (!Number.isInteger(protocolVersion) || protocolVersion <= 0) throw new Error(`protocolVersion must be a positive integer: ${protocolVersion}`);
+	return {
+		packageVersion,
+		protocolVersion
+	};
+};
+const isSupportedProtocolVersion = (protocolVersion) => protocolVersion === 1;
+const formatBrokerEndpointName = (identity) => {
+	assertEndpointIdentity(identity);
+	return `opentray-${identity.packageVersion}-p${identity.protocolVersion}`;
+};
+const formatBrokerStateRoot = (homeDir, identity) => {
+	assertEndpointIdentity(identity);
+	if (homeDir.length === 0) throw new Error("homeDir must not be empty");
+	return `${homeDir.replace(/[\\/]+$/u, "")}/.opentray/${identity.packageVersion}`;
+};
+const formatUnixSocketPath = (homeDir, identity) => `${formatBrokerStateRoot(homeDir, identity)}/opentray-p${identity.protocolVersion}.sock`;
+const formatWindowsPipeName = (identity) => `\\\\.\\pipe\\${formatBrokerEndpointName(identity)}`;
+const endpointComponentPattern = /^[0-9A-Za-z._+-]+$/u;
+const assertEndpointIdentity = (identity) => {
+	assertEndpointComponent(identity.packageVersion, "packageVersion");
+	if (!Number.isInteger(identity.protocolVersion) || identity.protocolVersion <= 0) throw new Error(`protocolVersion must be a positive integer: ${identity.protocolVersion}`);
+};
+const assertEndpointComponent = (value, name) => {
+	if (value.length === 0) throw new Error(`${name} must not be empty`);
+	if (!endpointComponentPattern.test(value)) throw new Error(`${name} contains invalid endpoint characters: ${value}`);
+};
+const parseServerFrame = (line) => {
+	try {
+		const value = JSON.parse(line);
+		if (!isServerFrame(value)) return {
+			ok: false,
+			error: "invalid server frame"
+		};
+		return {
+			ok: true,
+			frame: value
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: error instanceof Error ? error.message : "unknown parse error"
+		};
+	}
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isServerFrame = (value) => {
+	if (!isRecord(value) || typeof value.type !== "string") return false;
+	switch (value.type) {
+		case "ready": return typeof value.protocolVersion === "number" && typeof value.brokerVersion === "string" && typeof value.leaseId === "string";
+		case "surface-created": return typeof value.requestId === "string" && isRecord(value.surface);
+		case "default-surface": return typeof value.requestId === "string" && isRecord(value.surface);
+		case "tray-created": return typeof value.requestId === "string" && typeof value.surfaceId === "string" && typeof value.trayId === "string";
+		case "ack": return typeof value.requestId === "string";
+		case "daemon-health": return typeof value.requestId === "string" && isDaemonHealth(value.health);
+		case "event": return isTrayEvent(value.event);
+		case "ext-event": return typeof value.surfaceId === "string" && typeof value.trayId === "string" && typeof value.ext === "string";
+		case "error": return (value.requestId === void 0 || typeof value.requestId === "string") && typeof value.code === "string" && typeof value.message === "string";
+		default: return false;
+	}
+};
+const isDaemonHealth = (value) => {
+	if (!isRecord(value)) return false;
+	return typeof value.pid === "number" && typeof value.packageVersion === "string" && typeof value.protocolVersion === "number" && typeof value.endpoint === "string" && typeof value.sessionCount === "number" && Array.isArray(value.sessions) && value.sessions.every(isDaemonSessionHealth);
+};
+const isDaemonSessionHealth = (value) => isRecord(value) && typeof value.sessionId === "number" && (value.leaseId === void 0 || typeof value.leaseId === "string") && typeof value.initialized === "boolean";
+const isTrayEvent = (value) => {
+	if (!isRecord(value) || typeof value.type !== "string") return false;
+	switch (value.type) {
+		case "ready": return typeof value.surfaceId === "string";
+		case "menuClick": return typeof value.surfaceId === "string" && typeof value.trayId === "string" && typeof value.itemId === "number";
+		case "trayClick":
+		case "trayDoubleClick": return typeof value.surfaceId === "string" && isMouseButton(value.button) && typeof value.x === "number" && typeof value.y === "number";
+		default: return false;
+	}
+};
+const isMouseButton = (value) => value === "left" || value === "right" || value === "middle";
+//#endregion
+export { PROTOCOL_VERSION, createBrokerEndpointIdentity, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isServerFrame, isSupportedProtocolVersion, parseServerFrame };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["export type LeaseId = string;\nexport type RequestId = string;\nexport type SurfaceId = string;\nexport type TrayId = string;\nexport type MenuItemId = number;\n\nexport const PROTOCOL_VERSION = 1;\n\nexport interface BrokerEndpointIdentity {\n  packageVersion: string;\n  protocolVersion: number;\n}\n\nexport interface BrokerEndpointIdentityOptions {\n  packageVersion: string;\n  protocolVersion?: number;\n}\n\nexport const createBrokerEndpointIdentity = ({\n  packageVersion,\n  protocolVersion = PROTOCOL_VERSION,\n}: BrokerEndpointIdentityOptions): BrokerEndpointIdentity => {\n  assertEndpointComponent(packageVersion, \"packageVersion\");\n  if (!Number.isInteger(protocolVersion) || protocolVersion <= 0) {\n    throw new Error(`protocolVersion must be a positive integer: ${protocolVersion}`);\n  }\n\n  return {\n    packageVersion,\n    protocolVersion,\n  };\n};\n\nexport const isSupportedProtocolVersion = (protocolVersion: number): boolean =>\n  protocolVersion === PROTOCOL_VERSION;\n\nexport const formatBrokerEndpointName = (identity: BrokerEndpointIdentity): string => {\n  assertEndpointIdentity(identity);\n  return `opentray-${identity.packageVersion}-p${identity.protocolVersion}`;\n};\n\nexport const formatBrokerStateRoot = (homeDir: string, identity: BrokerEndpointIdentity): string => {\n  assertEndpointIdentity(identity);\n  if (homeDir.length === 0) {\n    throw new Error(\"homeDir must not be empty\");\n  }\n\n  const normalizedHome = homeDir.replace(/[\\\\/]+$/u, \"\");\n  return `${normalizedHome}/.opentray/${identity.packageVersion}`;\n};\n\nexport const formatUnixSocketPath = (homeDir: string, identity: BrokerEndpointIdentity): string =>\n  `${formatBrokerStateRoot(homeDir, identity)}/opentray-p${identity.protocolVersion}.sock`;\n\nexport const formatWindowsPipeName = (identity: BrokerEndpointIdentity): string =>\n  `\\\\\\\\.\\\\pipe\\\\${formatBrokerEndpointName(identity)}`;\n\nconst endpointComponentPattern = /^[0-9A-Za-z._+-]+$/u;\n\nconst assertEndpointIdentity = (identity: BrokerEndpointIdentity): void => {\n  assertEndpointComponent(identity.packageVersion, \"packageVersion\");\n  if (!Number.isInteger(identity.protocolVersion) || identity.protocolVersion <= 0) {\n    throw new Error(`protocolVersion must be a positive integer: ${identity.protocolVersion}`);\n  }\n};\n\nconst assertEndpointComponent = (value: string, name: string): void => {\n  if (value.length === 0) {\n    throw new Error(`${name} must not be empty`);\n  }\n  if (!endpointComponentPattern.test(value)) {\n    throw new Error(`${name} contains invalid endpoint characters: ${value}`);\n  }\n};\n\nexport interface SurfaceOptions {\n  appId: string;\n  title?: string;\n  icon?: Icon;\n  default?: boolean;\n}\n\nexport interface SurfaceRef {\n  surfaceId: SurfaceId;\n  appId: string;\n}\n\nexport interface TrayOptions {\n  trayId?: TrayId;\n  appId?: string;\n  title?: string;\n  tooltip?: Tooltip;\n  icon: Icon;\n  menu?: Menu;\n}\n\nexport interface Tooltip {\n  title: string;\n  description: string;\n}\n\nexport interface Menu {\n  items: MenuItem[];\n}\n\nexport type MenuItem =\n  | {\n      type: \"item\";\n      id: MenuItemId;\n      title: string;\n      enabled?: boolean;\n      shortcut?: string;\n    }\n  | {\n      type: \"check\";\n      id: MenuItemId;\n      title: string;\n      enabled?: boolean;\n      checked?: boolean;\n    }\n  | {\n      type: \"radio\";\n      id: MenuItemId;\n      title: string;\n      enabled?: boolean;\n      checked?: boolean;\n      group: number;\n    }\n  | {\n      type: \"separator\";\n    }\n  | {\n      type: \"submenu\";\n      title: string;\n      enabled?: boolean;\n      items: MenuItem[];\n    };\n\nexport type Icon =\n  | { type: \"rgba\"; data: Uint8Array | number[]; width: number; height: number }\n  | { type: \"encoded\"; data: Uint8Array | number[] }\n  | { type: \"file\"; path: string };\n\nexport interface Rect {\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n}\n\nexport type MouseButton = \"left\" | \"right\" | \"middle\";\n\nexport type TrayEvent =\n  | { type: \"ready\"; surfaceId: SurfaceId }\n  | { type: \"menuClick\"; surfaceId: SurfaceId; trayId: TrayId; itemId: MenuItemId }\n  | { type: \"trayClick\"; surfaceId: SurfaceId; button: MouseButton; x: number; y: number }\n  | { type: \"trayDoubleClick\"; surfaceId: SurfaceId; button: MouseButton; x: number; y: number };\n\nexport interface ExtensionScope {\n  surfaceId: SurfaceId;\n  trayId?: TrayId;\n  ext: string;\n}\n\nexport interface ExtensionEnvelope<TData = unknown> {\n  scope: ExtensionScope;\n  data: TData;\n}\n\nexport interface DaemonSessionHealth {\n  sessionId: number;\n  leaseId?: LeaseId;\n  initialized: boolean;\n}\n\nexport interface DaemonHealth {\n  pid: number;\n  packageVersion: string;\n  protocolVersion: number;\n  endpoint: string;\n  sessionCount: number;\n  sessions: DaemonSessionHealth[];\n}\n\nexport type ClientFrame =\n  | { type: \"init\"; protocolVersion: number; clientVersion: string }\n  | ClientRequestFrame\n  | { type: \"exit\" };\n\nexport type ClientRequestFrame =\n  | ({ type: \"create-surface\"; requestId: RequestId } & SurfaceOptions)\n  | { type: \"resolve-default-surface\"; requestId: RequestId }\n  | { type: \"create-tray\"; requestId: RequestId; surface: SurfaceRef; tray: TrayOptions }\n  | { type: \"destroy-tray\"; requestId: RequestId; surfaceId: SurfaceId; trayId: TrayId }\n  | { type: \"set-tray-menu\"; requestId: RequestId; surfaceId: SurfaceId; trayId: TrayId; menu: Menu }\n  | { type: \"set-tray-icon\"; requestId: RequestId; surfaceId: SurfaceId; trayId: TrayId; icon: Icon }\n  | { type: \"set-tray-tooltip\"; requestId: RequestId; surfaceId: SurfaceId; trayId: TrayId; tooltip: Tooltip }\n  | { type: \"load-ext\"; requestId: RequestId; surfaceId: SurfaceId; name: string; path: string }\n  | { type: \"ext-command\"; requestId: RequestId; surfaceId: SurfaceId; trayId: TrayId; ext: string; data: unknown }\n  | { type: \"unload-ext\"; requestId: RequestId; surfaceId: SurfaceId; name: string }\n  | { type: \"health\"; requestId: RequestId };\n\nexport type ServerFrame =\n  | { type: \"ready\"; protocolVersion: number; brokerVersion: string; leaseId: LeaseId }\n  | { type: \"surface-created\"; requestId: RequestId; surface: SurfaceRef }\n  | { type: \"default-surface\"; requestId: RequestId; surface: SurfaceRef }\n  | { type: \"tray-created\"; requestId: RequestId; surfaceId: SurfaceId; trayId: TrayId }\n  | { type: \"ack\"; requestId: RequestId }\n  | { type: \"daemon-health\"; requestId: RequestId; health: DaemonHealth }\n  | { type: \"event\"; event: TrayEvent }\n  | { type: \"ext-event\"; surfaceId: SurfaceId; trayId: TrayId; ext: string; data: unknown }\n  | { type: \"error\"; requestId?: RequestId; code: string; message: string };\n\nexport interface ParseResult<T> {\n  ok: boolean;\n  frame?: T;\n  error?: string;\n}\n\nexport const parseServerFrame = (line: string): ParseResult<ServerFrame> => {\n  try {\n    const value: unknown = JSON.parse(line);\n    if (!isServerFrame(value)) {\n      return { ok: false, error: \"invalid server frame\" };\n    }\n    return { ok: true, frame: value };\n  } catch (error) {\n    return {\n      ok: false,\n      error: error instanceof Error ? error.message : \"unknown parse error\",\n    };\n  }\n};\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === \"object\" && value !== null && !Array.isArray(value);\n\nexport const isServerFrame = (value: unknown): value is ServerFrame => {\n  if (!isRecord(value) || typeof value.type !== \"string\") {\n    return false;\n  }\n\n  switch (value.type) {\n    case \"ready\":\n      return (\n        typeof value.protocolVersion === \"number\" &&\n        typeof value.brokerVersion === \"string\" &&\n        typeof value.leaseId === \"string\"\n      );\n    case \"surface-created\":\n      return typeof value.requestId === \"string\" && isRecord(value.surface);\n    case \"default-surface\":\n      return typeof value.requestId === \"string\" && isRecord(value.surface);\n    case \"tray-created\":\n      return (\n        typeof value.requestId === \"string\" &&\n        typeof value.surfaceId === \"string\" &&\n        typeof value.trayId === \"string\"\n      );\n    case \"ack\":\n      return typeof value.requestId === \"string\";\n    case \"daemon-health\":\n      return typeof value.requestId === \"string\" && isDaemonHealth(value.health);\n    case \"event\":\n      return isTrayEvent(value.event);\n    case \"ext-event\":\n      return (\n        typeof value.surfaceId === \"string\" &&\n        typeof value.trayId === \"string\" &&\n        typeof value.ext === \"string\"\n      );\n    case \"error\":\n      return (\n        (value.requestId === undefined || typeof value.requestId === \"string\") &&\n        typeof value.code === \"string\" &&\n        typeof value.message === \"string\"\n      );\n    default:\n      return false;\n  }\n};\n\nconst isDaemonHealth = (value: unknown): value is DaemonHealth => {\n  if (!isRecord(value)) {\n    return false;\n  }\n\n  return (\n    typeof value.pid === \"number\" &&\n    typeof value.packageVersion === \"string\" &&\n    typeof value.protocolVersion === \"number\" &&\n    typeof value.endpoint === \"string\" &&\n    typeof value.sessionCount === \"number\" &&\n    Array.isArray(value.sessions) &&\n    value.sessions.every(isDaemonSessionHealth)\n  );\n};\n\nconst isDaemonSessionHealth = (value: unknown): value is DaemonSessionHealth =>\n  isRecord(value) &&\n  typeof value.sessionId === \"number\" &&\n  (value.leaseId === undefined || typeof value.leaseId === \"string\") &&\n  typeof value.initialized === \"boolean\";\n\nconst isTrayEvent = (value: unknown): value is TrayEvent => {\n  if (!isRecord(value) || typeof value.type !== \"string\") {\n    return false;\n  }\n\n  switch (value.type) {\n    case \"ready\":\n      return typeof value.surfaceId === \"string\";\n    case \"menuClick\":\n      return (\n        typeof value.surfaceId === \"string\" &&\n        typeof value.trayId === \"string\" &&\n        typeof value.itemId === \"number\"\n      );\n    case \"trayClick\":\n    case \"trayDoubleClick\":\n      return (\n        typeof value.surfaceId === \"string\" &&\n        isMouseButton(value.button) &&\n        typeof value.x === \"number\" &&\n        typeof value.y === \"number\"\n      );\n    default:\n      return false;\n  }\n};\n\nconst isMouseButton = (value: unknown): value is MouseButton =>\n  value === \"left\" || value === \"right\" || value === \"middle\";\n"],"mappings":"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"}

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@opentray/spec",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "description": "Shared TypeScript protocol and contract types for OpenTray.",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jixoai/opentray"
+  },
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
     },
     "./package.json": "./package.json"
   },
@@ -15,5 +19,16 @@
     "dist",
     "README.md"
   ],
-  "sideEffects": false
+  "sideEffects": false,
+  "devDependencies": {
+    "tsdown": "^0.22.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts",
+    "example:parse": "bun run examples/parse-frame.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }