@opentray/spec 0.0.0-alpha-20260605111358

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +30 -0
  2. package/dist/index.d.mts +276 -0
  3. package/dist/index.d.mts.map +1 -0
  4. package/dist/index.mjs +88 -0
  5. package/dist/index.mjs.map +1 -0
  6. package/package.json +34 -0
package/README.md ADDED
@@ -0,0 +1,30 @@
1
+ # @opentray/spec
2
+
3
+ Shared TypeScript protocol and contract package for OpenTray.
4
+
5
+ ## Role
6
+
7
+ - Define JSON-RPC payload shapes.
8
+ - Define broker protocol version and endpoint identity helpers.
9
+ - Define public `Space`, `Tray`, `Session`, and extension contract types.
10
+ - Keep protocol types reusable by the `opentray` package and official extensions.
11
+
12
+ This package must stay platform-neutral and must not import native implementation packages.
13
+
14
+ ## Example
15
+
16
+ Run a protocol parser example that shows successful server-frame parsing and malformed-frame rejection:
17
+
18
+ ```bash
19
+ pnpm --filter @opentray/spec example:parse
20
+ ```
21
+
22
+ Endpoint identity is version-scoped during the current unstable broker stage:
23
+
24
+ ```ts
25
+ import { createBrokerEndpointIdentity, formatUnixSocketPath } from "@opentray/spec";
26
+
27
+ const identity = createBrokerEndpointIdentity({ packageVersion: "0.1.0" });
28
+ console.log(formatUnixSocketPath("~", identity));
29
+ // ~/.opentray/0.1.0/opentray-p1.sock
30
+ ```
package/dist/index.d.mts ADDED
@@ -0,0 +1,276 @@
1
+ //#region src/index.d.ts
2
+ type SessionId = string;
3
+ type RequestId = string;
4
+ type SpaceId = string;
5
+ type TrayId = string;
6
+ type MenuItemId = number;
7
+ /** @deprecated Use `SessionId`. */
8
+ type LeaseId = SessionId;
9
+ /** @deprecated Use `SpaceId`. */
10
+ type SurfaceId = SpaceId;
11
+ declare const PROTOCOL_VERSION = 1;
12
+ interface BrokerEndpointIdentity {
13
+ packageVersion: string;
14
+ protocolVersion: number;
15
+ }
16
+ interface BrokerEndpointIdentityOptions {
17
+ packageVersion: string;
18
+ protocolVersion?: number;
19
+ }
20
+ declare const createBrokerEndpointIdentity: ({
21
+ packageVersion,
22
+ protocolVersion
23
+ }: BrokerEndpointIdentityOptions) => BrokerEndpointIdentity;
24
+ declare const isSupportedProtocolVersion: (protocolVersion: number) => boolean;
25
+ declare const formatBrokerEndpointName: (identity: BrokerEndpointIdentity) => string;
26
+ declare const formatBrokerStateRoot: (homeDir: string, identity: BrokerEndpointIdentity) => string;
27
+ declare const formatUnixSocketPath: (homeDir: string, identity: BrokerEndpointIdentity) => string;
28
+ declare const formatWindowsPipeName: (identity: BrokerEndpointIdentity) => string;
29
+ interface SpaceOptions {
30
+ id?: SpaceId;
31
+ title?: string;
32
+ icon?: Icon;
33
+ default?: boolean;
34
+ }
35
+ /** @deprecated Use `SpaceOptions`. */
36
+ type SurfaceOptions = SpaceOptions;
37
+ interface SpaceRef {
38
+ spaceId: SpaceId;
39
+ }
40
+ /** @deprecated Use `SpaceRef`. */
41
+ type SurfaceRef = SpaceRef;
42
+ interface TrayOptions {
43
+ trayId?: TrayId;
44
+ appId?: string;
45
+ title?: string;
46
+ tooltip?: Tooltip;
47
+ icon: Icon;
48
+ menu?: Menu;
49
+ }
50
+ interface Tooltip {
51
+ title: string;
52
+ description: string;
53
+ }
54
+ interface Menu {
55
+ items: MenuItem[];
56
+ }
57
+ type MenuItem = {
58
+ type: "item";
59
+ id: MenuItemId;
60
+ title: string;
61
+ primaryEvent?: boolean;
62
+ enabled?: boolean;
63
+ shortcut?: string;
64
+ } | {
65
+ type: "check";
66
+ id: MenuItemId;
67
+ title: string;
68
+ enabled?: boolean;
69
+ checked?: boolean;
70
+ } | {
71
+ type: "radio";
72
+ id: MenuItemId;
73
+ title: string;
74
+ enabled?: boolean;
75
+ checked?: boolean;
76
+ group: number;
77
+ } | {
78
+ type: "separator";
79
+ } | {
80
+ type: "submenu";
81
+ title: string;
82
+ enabled?: boolean;
83
+ items: MenuItem[];
84
+ };
85
+ type Icon = {
86
+ type: "rgba";
87
+ data: Uint8Array | number[];
88
+ width: number;
89
+ height: number;
90
+ } | {
91
+ type: "encoded";
92
+ data: Uint8Array | number[];
93
+ } | {
94
+ type: "file";
95
+ path: string;
96
+ };
97
+ interface Rect {
98
+ x: number;
99
+ y: number;
100
+ width: number;
101
+ height: number;
102
+ }
103
+ type TrayBoundsKind = "native" | "inferred" | "unavailable";
104
+ interface TrayBoundsResult {
105
+ kind: TrayBoundsKind;
106
+ source: string;
107
+ rect: Rect | null;
108
+ }
109
+ type MouseButton = "left" | "right" | "middle";
110
+ type TrayEvent = {
111
+ type: "ready";
112
+ spaceId: SpaceId;
113
+ } | {
114
+ type: "menuClick";
115
+ spaceId: SpaceId;
116
+ trayId: TrayId;
117
+ itemId: MenuItemId;
118
+ } | {
119
+ type: "trayClick";
120
+ spaceId: SpaceId;
121
+ button: MouseButton;
122
+ x: number;
123
+ y: number;
124
+ } | {
125
+ type: "trayDoubleClick";
126
+ spaceId: SpaceId;
127
+ button: MouseButton;
128
+ x: number;
129
+ y: number;
130
+ };
131
+ interface ExtensionScope {
132
+ spaceId: SpaceId;
133
+ trayId?: TrayId;
134
+ ext: string;
135
+ }
136
+ interface ExtensionEnvelope<TData = unknown> {
137
+ scope: ExtensionScope;
138
+ data: TData;
139
+ }
140
+ interface DaemonSessionHealth {
141
+ sessionId: number;
142
+ internalLeaseId?: SessionId;
143
+ initialized: boolean;
144
+ }
145
+ interface DaemonHealth {
146
+ pid: number;
147
+ packageVersion: string;
148
+ protocolVersion: number;
149
+ endpoint: string;
150
+ sessionCount: number;
151
+ sessions: DaemonSessionHealth[];
152
+ }
153
+ type ClientFrame = {
154
+ type: "init";
155
+ protocolVersion: number;
156
+ clientVersion: string;
157
+ } | ClientRequestFrame | {
158
+ type: "exit";
159
+ };
160
+ type ClientRequestFrame = ({
161
+ type: "create-space";
162
+ requestId: RequestId;
163
+ } & SpaceOptions) | {
164
+ type: "resolve-default-space";
165
+ requestId: RequestId;
166
+ } | {
167
+ type: "create-tray";
168
+ requestId: RequestId;
169
+ space: SpaceRef;
170
+ tray: TrayOptions;
171
+ } | {
172
+ type: "destroy-tray";
173
+ requestId: RequestId;
174
+ spaceId: SpaceId;
175
+ trayId: TrayId;
176
+ } | {
177
+ type: "get-tray-bounds";
178
+ requestId: RequestId;
179
+ spaceId: SpaceId;
180
+ trayId: TrayId;
181
+ } | {
182
+ type: "set-tray-menu";
183
+ requestId: RequestId;
184
+ spaceId: SpaceId;
185
+ trayId: TrayId;
186
+ menu: Menu;
187
+ } | {
188
+ type: "set-tray-icon";
189
+ requestId: RequestId;
190
+ spaceId: SpaceId;
191
+ trayId: TrayId;
192
+ icon: Icon;
193
+ } | {
194
+ type: "set-tray-tooltip";
195
+ requestId: RequestId;
196
+ spaceId: SpaceId;
197
+ trayId: TrayId;
198
+ tooltip: Tooltip;
199
+ } | {
200
+ type: "load-ext";
201
+ requestId: RequestId;
202
+ spaceId: SpaceId;
203
+ name: string;
204
+ path: string;
205
+ } | {
206
+ type: "ext-command";
207
+ requestId: RequestId;
208
+ spaceId: SpaceId;
209
+ trayId: TrayId;
210
+ ext: string;
211
+ data: unknown;
212
+ } | {
213
+ type: "unload-ext";
214
+ requestId: RequestId;
215
+ spaceId: SpaceId;
216
+ name: string;
217
+ } | {
218
+ type: "health";
219
+ requestId: RequestId;
220
+ };
221
+ type ServerFrame = {
222
+ type: "ready";
223
+ protocolVersion: number;
224
+ brokerVersion: string;
225
+ sessionId: SessionId;
226
+ } | {
227
+ type: "space-created";
228
+ requestId: RequestId;
229
+ space: SpaceRef;
230
+ } | {
231
+ type: "default-space";
232
+ requestId: RequestId;
233
+ space: SpaceRef;
234
+ } | {
235
+ type: "tray-created";
236
+ requestId: RequestId;
237
+ spaceId: SpaceId;
238
+ trayId: TrayId;
239
+ } | {
240
+ type: "tray-bounds";
241
+ requestId: RequestId;
242
+ spaceId: SpaceId;
243
+ trayId: TrayId;
244
+ bounds: TrayBoundsResult;
245
+ } | {
246
+ type: "ack";
247
+ requestId: RequestId;
248
+ } | {
249
+ type: "daemon-health";
250
+ requestId: RequestId;
251
+ health: DaemonHealth;
252
+ } | {
253
+ type: "event";
254
+ event: TrayEvent;
255
+ } | {
256
+ type: "ext-event";
257
+ spaceId: SpaceId;
258
+ trayId: TrayId;
259
+ ext: string;
260
+ data: unknown;
261
+ } | {
262
+ type: "error";
263
+ requestId?: RequestId;
264
+ code: string;
265
+ message: string;
266
+ };
267
+ interface ParseResult<T> {
268
+ ok: boolean;
269
+ frame?: T;
270
+ error?: string;
271
+ }
272
+ declare const parseServerFrame: (line: string) => ParseResult<ServerFrame>;
273
+ declare const isServerFrame: (value: unknown) => value is ServerFrame;
274
+ //#endregion
275
+ export { BrokerEndpointIdentity, BrokerEndpointIdentityOptions, ClientFrame, ClientRequestFrame, DaemonHealth, DaemonSessionHealth, ExtensionEnvelope, ExtensionScope, Icon, LeaseId, Menu, MenuItem, MenuItemId, MouseButton, PROTOCOL_VERSION, ParseResult, Rect, RequestId, ServerFrame, SessionId, SpaceId, SpaceOptions, SpaceRef, SurfaceId, SurfaceOptions, SurfaceRef, Tooltip, TrayBoundsKind, TrayBoundsResult, TrayEvent, TrayId, TrayOptions, createBrokerEndpointIdentity, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isServerFrame, isSupportedProtocolVersion, parseServerFrame };
276
+ //# sourceMappingURL=index.d.mts.map
package/dist/index.d.mts.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":"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"}
package/dist/index.mjs ADDED
@@ -0,0 +1,88 @@
1
+ //#region src/index.ts
2
+ const PROTOCOL_VERSION = 1;
3
+ const createBrokerEndpointIdentity = ({ packageVersion, protocolVersion = 1 }) => {
4
+ assertEndpointComponent(packageVersion, "packageVersion");
5
+ if (!Number.isInteger(protocolVersion) || protocolVersion <= 0) throw new Error(`protocolVersion must be a positive integer: ${protocolVersion}`);
6
+ return {
7
+ packageVersion,
8
+ protocolVersion
9
+ };
10
+ };
11
+ const isSupportedProtocolVersion = (protocolVersion) => protocolVersion === 1;
12
+ const formatBrokerEndpointName = (identity) => {
13
+ assertEndpointIdentity(identity);
14
+ return `opentray-${identity.packageVersion}-p${identity.protocolVersion}`;
15
+ };
16
+ const formatBrokerStateRoot = (homeDir, identity) => {
17
+ assertEndpointIdentity(identity);
18
+ if (homeDir.length === 0) throw new Error("homeDir must not be empty");
19
+ return `${homeDir.replace(/[\\/]+$/u, "")}/.opentray/${identity.packageVersion}`;
20
+ };
21
+ const formatUnixSocketPath = (homeDir, identity) => `${formatBrokerStateRoot(homeDir, identity)}/opentray-p${identity.protocolVersion}.sock`;
22
+ const formatWindowsPipeName = (identity) => `\\\\.\\pipe\\${formatBrokerEndpointName(identity)}`;
23
+ const endpointComponentPattern = /^[0-9A-Za-z._+-]+$/u;
24
+ const assertEndpointIdentity = (identity) => {
25
+ assertEndpointComponent(identity.packageVersion, "packageVersion");
26
+ if (!Number.isInteger(identity.protocolVersion) || identity.protocolVersion <= 0) throw new Error(`protocolVersion must be a positive integer: ${identity.protocolVersion}`);
27
+ };
28
+ const assertEndpointComponent = (value, name) => {
29
+ if (value.length === 0) throw new Error(`${name} must not be empty`);
30
+ if (!endpointComponentPattern.test(value)) throw new Error(`${name} contains invalid endpoint characters: ${value}`);
31
+ };
32
+ const parseServerFrame = (line) => {
33
+ try {
34
+ const value = JSON.parse(line);
35
+ if (!isServerFrame(value)) return {
36
+ ok: false,
37
+ error: "invalid server frame"
38
+ };
39
+ return {
40
+ ok: true,
41
+ frame: value
42
+ };
43
+ } catch (error) {
44
+ return {
45
+ ok: false,
46
+ error: error instanceof Error ? error.message : "unknown parse error"
47
+ };
48
+ }
49
+ };
50
+ const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
51
+ const isServerFrame = (value) => {
52
+ if (!isRecord(value) || typeof value.type !== "string") return false;
53
+ switch (value.type) {
54
+ case "ready": return typeof value.protocolVersion === "number" && typeof value.brokerVersion === "string" && typeof value.sessionId === "string";
55
+ case "space-created": return typeof value.requestId === "string" && isRecord(value.space);
56
+ case "default-space": return typeof value.requestId === "string" && isRecord(value.space);
57
+ case "tray-created": return typeof value.requestId === "string" && typeof value.spaceId === "string" && typeof value.trayId === "string";
58
+ case "tray-bounds": return typeof value.requestId === "string" && typeof value.spaceId === "string" && typeof value.trayId === "string" && isTrayBoundsResult(value.bounds);
59
+ case "ack": return typeof value.requestId === "string";
60
+ case "daemon-health": return typeof value.requestId === "string" && isDaemonHealth(value.health);
61
+ case "event": return isTrayEvent(value.event);
62
+ case "ext-event": return typeof value.spaceId === "string" && typeof value.trayId === "string" && typeof value.ext === "string";
63
+ case "error": return (value.requestId === void 0 || typeof value.requestId === "string") && typeof value.code === "string" && typeof value.message === "string";
64
+ default: return false;
65
+ }
66
+ };
67
+ const isDaemonHealth = (value) => {
68
+ if (!isRecord(value)) return false;
69
+ 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);
70
+ };
71
+ const isDaemonSessionHealth = (value) => isRecord(value) && typeof value.sessionId === "number" && (value.internalLeaseId === void 0 || typeof value.internalLeaseId === "string") && typeof value.initialized === "boolean";
72
+ const isRect = (value) => isRecord(value) && typeof value.x === "number" && typeof value.y === "number" && typeof value.width === "number" && typeof value.height === "number";
73
+ const isTrayBoundsResult = (value) => isRecord(value) && (value.kind === "native" || value.kind === "inferred" || value.kind === "unavailable") && typeof value.source === "string" && (value.rect === null || isRect(value.rect));
74
+ const isTrayEvent = (value) => {
75
+ if (!isRecord(value) || typeof value.type !== "string") return false;
76
+ switch (value.type) {
77
+ case "ready": return typeof value.spaceId === "string";
78
+ case "menuClick": return typeof value.spaceId === "string" && typeof value.trayId === "string" && typeof value.itemId === "number";
79
+ case "trayClick":
80
+ case "trayDoubleClick": return typeof value.spaceId === "string" && isMouseButton(value.button) && typeof value.x === "number" && typeof value.y === "number";
81
+ default: return false;
82
+ }
83
+ };
84
+ const isMouseButton = (value) => value === "left" || value === "right" || value === "middle";
85
+ //#endregion
86
+ export { PROTOCOL_VERSION, createBrokerEndpointIdentity, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isServerFrame, isSupportedProtocolVersion, parseServerFrame };
87
+
88
+ //# sourceMappingURL=index.mjs.map
package/dist/index.mjs.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["export type SessionId = string;\nexport type RequestId = string;\nexport type SpaceId = string;\nexport type TrayId = string;\nexport type MenuItemId = number;\n\n/** @deprecated Use `SessionId`. */\nexport type LeaseId = SessionId;\n/** @deprecated Use `SpaceId`. */\nexport type SurfaceId = SpaceId;\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 SpaceOptions {\n id?: SpaceId;\n title?: string;\n icon?: Icon;\n default?: boolean;\n}\n\n/** @deprecated Use `SpaceOptions`. */\nexport type SurfaceOptions = SpaceOptions;\n\nexport interface SpaceRef {\n spaceId: SpaceId;\n}\n\n/** @deprecated Use `SpaceRef`. */\nexport type SurfaceRef = SpaceRef;\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 primaryEvent?: boolean;\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 TrayBoundsKind = \"native\" | \"inferred\" | \"unavailable\";\n\nexport interface TrayBoundsResult {\n kind: TrayBoundsKind;\n source: string;\n rect: Rect | null;\n}\n\nexport type MouseButton = \"left\" | \"right\" | \"middle\";\n\nexport type TrayEvent =\n | { type: \"ready\"; spaceId: SpaceId }\n | { type: \"menuClick\"; spaceId: SpaceId; trayId: TrayId; itemId: MenuItemId }\n | { type: \"trayClick\"; spaceId: SpaceId; button: MouseButton; x: number; y: number }\n | { type: \"trayDoubleClick\"; spaceId: SpaceId; button: MouseButton; x: number; y: number };\n\nexport interface ExtensionScope {\n spaceId: SpaceId;\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 internalLeaseId?: SessionId;\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-space\"; requestId: RequestId } & SpaceOptions)\n | { type: \"resolve-default-space\"; requestId: RequestId }\n | { type: \"create-tray\"; requestId: RequestId; space: SpaceRef; tray: TrayOptions }\n | { type: \"destroy-tray\"; requestId: RequestId; spaceId: SpaceId; trayId: TrayId }\n | { type: \"get-tray-bounds\"; requestId: RequestId; spaceId: SpaceId; trayId: TrayId }\n | { type: \"set-tray-menu\"; requestId: RequestId; spaceId: SpaceId; trayId: TrayId; menu: Menu }\n | { type: \"set-tray-icon\"; requestId: RequestId; spaceId: SpaceId; trayId: TrayId; icon: Icon }\n | { type: \"set-tray-tooltip\"; requestId: RequestId; spaceId: SpaceId; trayId: TrayId; tooltip: Tooltip }\n | { type: \"load-ext\"; requestId: RequestId; spaceId: SpaceId; name: string; path: string }\n | { type: \"ext-command\"; requestId: RequestId; spaceId: SpaceId; trayId: TrayId; ext: string; data: unknown }\n | { type: \"unload-ext\"; requestId: RequestId; spaceId: SpaceId; name: string }\n | { type: \"health\"; requestId: RequestId };\n\nexport type ServerFrame =\n | { type: \"ready\"; protocolVersion: number; brokerVersion: string; sessionId: SessionId }\n | { type: \"space-created\"; requestId: RequestId; space: SpaceRef }\n | { type: \"default-space\"; requestId: RequestId; space: SpaceRef }\n | { type: \"tray-created\"; requestId: RequestId; spaceId: SpaceId; trayId: TrayId }\n | { type: \"tray-bounds\"; requestId: RequestId; spaceId: SpaceId; trayId: TrayId; bounds: TrayBoundsResult }\n | { type: \"ack\"; requestId: RequestId }\n | { type: \"daemon-health\"; requestId: RequestId; health: DaemonHealth }\n | { type: \"event\"; event: TrayEvent }\n | { type: \"ext-event\"; spaceId: SpaceId; 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.sessionId === \"string\"\n );\n case \"space-created\":\n return typeof value.requestId === \"string\" && isRecord(value.space);\n case \"default-space\":\n return typeof value.requestId === \"string\" && isRecord(value.space);\n case \"tray-created\":\n return (\n typeof value.requestId === \"string\" &&\n typeof value.spaceId === \"string\" &&\n typeof value.trayId === \"string\"\n );\n case \"tray-bounds\":\n return (\n typeof value.requestId === \"string\" &&\n typeof value.spaceId === \"string\" &&\n typeof value.trayId === \"string\" &&\n isTrayBoundsResult(value.bounds)\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.spaceId === \"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.internalLeaseId === undefined || typeof value.internalLeaseId === \"string\") &&\n typeof value.initialized === \"boolean\";\n\nconst isRect = (value: unknown): value is Rect =>\n isRecord(value) &&\n typeof value.x === \"number\" &&\n typeof value.y === \"number\" &&\n typeof value.width === \"number\" &&\n typeof value.height === \"number\";\n\nconst isTrayBoundsResult = (value: unknown): value is TrayBoundsResult =>\n isRecord(value) &&\n (value.kind === \"native\" || value.kind === \"inferred\" || value.kind === \"unavailable\") &&\n typeof value.source === \"string\" &&\n (value.rect === null || isRect(value.rect));\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.spaceId === \"string\";\n case \"menuClick\":\n return (\n typeof value.spaceId === \"string\" &&\n typeof value.trayId === \"string\" &&\n typeof value.itemId === \"number\"\n );\n case \"trayClick\":\n case \"trayDoubleClick\":\n return (\n typeof value.spaceId === \"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":";AAWA,MAAa,mBAAmB;AAYhC,MAAa,gCAAgC,EAC3C,gBACA,kBAAA,QAC2D;CAC3D,wBAAwB,gBAAgB,gBAAgB;CACxD,IAAI,CAAC,OAAO,UAAU,eAAe,KAAK,mBAAmB,GAC3D,MAAM,IAAI,MAAM,+CAA+C,iBAAiB;CAGlF,OAAO;EACL;EACA;CACF;AACF;AAEA,MAAa,8BAA8B,oBACzC,oBAAA;AAEF,MAAa,4BAA4B,aAA6C;CACpF,uBAAuB,QAAQ;CAC/B,OAAO,YAAY,SAAS,eAAe,IAAI,SAAS;AAC1D;AAEA,MAAa,yBAAyB,SAAiB,aAA6C;CAClG,uBAAuB,QAAQ;CAC/B,IAAI,QAAQ,WAAW,GACrB,MAAM,IAAI,MAAM,2BAA2B;CAI7C,OAAO,GADgB,QAAQ,QAAQ,YAAY,EAC5B,EAAE,aAAa,SAAS;AACjD;AAEA,MAAa,wBAAwB,SAAiB,aACpD,GAAG,sBAAsB,SAAS,QAAQ,EAAE,aAAa,SAAS,gBAAgB;AAEpF,MAAa,yBAAyB,aACpC,gBAAgB,yBAAyB,QAAQ;AAEnD,MAAM,2BAA2B;AAEjC,MAAM,0BAA0B,aAA2C;CACzE,wBAAwB,SAAS,gBAAgB,gBAAgB;CACjE,IAAI,CAAC,OAAO,UAAU,SAAS,eAAe,KAAK,SAAS,mBAAmB,GAC7E,MAAM,IAAI,MAAM,+CAA+C,SAAS,iBAAiB;AAE7F;AAEA,MAAM,2BAA2B,OAAe,SAAuB;CACrE,IAAI,MAAM,WAAW,GACnB,MAAM,IAAI,MAAM,GAAG,KAAK,mBAAmB;CAE7C,IAAI,CAAC,yBAAyB,KAAK,KAAK,GACtC,MAAM,IAAI,MAAM,GAAG,KAAK,yCAAyC,OAAO;AAE5E;AAkKA,MAAa,oBAAoB,SAA2C;CAC1E,IAAI;EACF,MAAM,QAAiB,KAAK,MAAM,IAAI;EACtC,IAAI,CAAC,cAAc,KAAK,GACtB,OAAO;GAAE,IAAI;GAAO,OAAO;EAAuB;EAEpD,OAAO;GAAE,IAAI;GAAM,OAAO;EAAM;CAClC,SAAS,OAAO;EACd,OAAO;GACL,IAAI;GACJ,OAAO,iBAAiB,QAAQ,MAAM,UAAU;EAClD;CACF;AACF;AAEA,MAAM,YAAY,UAChB,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAErE,MAAa,iBAAiB,UAAyC;CACrE,IAAI,CAAC,SAAS,KAAK,KAAK,OAAO,MAAM,SAAS,UAC5C,OAAO;CAGT,QAAQ,MAAM,MAAd;EACE,KAAK,SACH,OACE,OAAO,MAAM,oBAAoB,YACjC,OAAO,MAAM,kBAAkB,YAC/B,OAAO,MAAM,cAAc;EAE/B,KAAK,iBACH,OAAO,OAAO,MAAM,cAAc,YAAY,SAAS,MAAM,KAAK;EACpE,KAAK,iBACH,OAAO,OAAO,MAAM,cAAc,YAAY,SAAS,MAAM,KAAK;EACpE,KAAK,gBACH,OACE,OAAO,MAAM,cAAc,YAC3B,OAAO,MAAM,YAAY,YACzB,OAAO,MAAM,WAAW;EAE5B,KAAK,eACH,OACE,OAAO,MAAM,cAAc,YAC3B,OAAO,MAAM,YAAY,YACzB,OAAO,MAAM,WAAW,YACxB,mBAAmB,MAAM,MAAM;EAEnC,KAAK,OACH,OAAO,OAAO,MAAM,cAAc;EACpC,KAAK,iBACH,OAAO,OAAO,MAAM,cAAc,YAAY,eAAe,MAAM,MAAM;EAC3E,KAAK,SACH,OAAO,YAAY,MAAM,KAAK;EAChC,KAAK,aACH,OACE,OAAO,MAAM,YAAY,YACzB,OAAO,MAAM,WAAW,YACxB,OAAO,MAAM,QAAQ;EAEzB,KAAK,SACH,QACG,MAAM,cAAc,KAAA,KAAa,OAAO,MAAM,cAAc,aAC7D,OAAO,MAAM,SAAS,YACtB,OAAO,MAAM,YAAY;EAE7B,SACE,OAAO;CACX;AACF;AAEA,MAAM,kBAAkB,UAA0C;CAChE,IAAI,CAAC,SAAS,KAAK,GACjB,OAAO;CAGT,OACE,OAAO,MAAM,QAAQ,YACrB,OAAO,MAAM,mBAAmB,YAChC,OAAO,MAAM,oBAAoB,YACjC,OAAO,MAAM,aAAa,YAC1B,OAAO,MAAM,iBAAiB,YAC9B,MAAM,QAAQ,MAAM,QAAQ,KAC5B,MAAM,SAAS,MAAM,qBAAqB;AAE9C;AAEA,MAAM,yBAAyB,UAC7B,SAAS,KAAK,KACd,OAAO,MAAM,cAAc,aAC1B,MAAM,oBAAoB,KAAA,KAAa,OAAO,MAAM,oBAAoB,aACzE,OAAO,MAAM,gBAAgB;AAE/B,MAAM,UAAU,UACd,SAAS,KAAK,KACd,OAAO,MAAM,MAAM,YACnB,OAAO,MAAM,MAAM,YACnB,OAAO,MAAM,UAAU,YACvB,OAAO,MAAM,WAAW;AAE1B,MAAM,sBAAsB,UAC1B,SAAS,KAAK,MACb,MAAM,SAAS,YAAY,MAAM,SAAS,cAAc,MAAM,SAAS,kBACxE,OAAO,MAAM,WAAW,aACvB,MAAM,SAAS,QAAQ,OAAO,MAAM,IAAI;AAE3C,MAAM,eAAe,UAAuC;CAC1D,IAAI,CAAC,SAAS,KAAK,KAAK,OAAO,MAAM,SAAS,UAC5C,OAAO;CAGT,QAAQ,MAAM,MAAd;EACE,KAAK,SACH,OAAO,OAAO,MAAM,YAAY;EAClC,KAAK,aACH,OACE,OAAO,MAAM,YAAY,YACzB,OAAO,MAAM,WAAW,YACxB,OAAO,MAAM,WAAW;EAE5B,KAAK;EACL,KAAK,mBACH,OACE,OAAO,MAAM,YAAY,YACzB,cAAc,MAAM,MAAM,KAC1B,OAAO,MAAM,MAAM,YACnB,OAAO,MAAM,MAAM;EAEvB,SACE,OAAO;CACX;AACF;AAEA,MAAM,iBAAiB,UACrB,UAAU,UAAU,UAAU,WAAW,UAAU"}
package/package.json ADDED
@@ -0,0 +1,34 @@
1
+ {
2
+ "name": "@opentray/spec",
3
+ "version": "0.0.0-alpha-20260605111358",
4
+ "description": "Shared TypeScript protocol and contract types for OpenTray.",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "https://github.com/jixoai/opentray"
10
+ },
11
+ "exports": {
12
+ ".": {
13
+ "types": "./dist/index.d.mts",
14
+ "import": "./dist/index.mjs"
15
+ },
16
+ "./package.json": "./package.json"
17
+ },
18
+ "files": [
19
+ "dist",
20
+ "README.md"
21
+ ],
22
+ "sideEffects": false,
23
+ "devDependencies": {
24
+ "tsdown": "^0.22.1",
25
+ "typescript": "^6.0.3",
26
+ "vitest": "^4.1.7"
27
+ },
28
+ "scripts": {
29
+ "build": "tsdown src/index.ts --format esm --dts",
30
+ "example:parse": "bun run examples/parse-frame.ts",
31
+ "test": "vitest run",
32
+ "typecheck": "tsc --noEmit"
33
+ }
34
+ }