@decaf-ts/for-os 0.0.0-stage → 0.2.7

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 (77) hide show
  1. package/LICENSE.md +21 -0
  2. package/README.md +380 -2
  3. package/lib/cjs/errors.cjs +73 -0
  4. package/lib/cjs/errors.cjs.map +1 -0
  5. package/lib/cjs/index.cjs +46 -0
  6. package/lib/cjs/index.cjs.map +1 -0
  7. package/lib/cjs/native/icons.cjs +123 -0
  8. package/lib/cjs/native/icons.cjs.map +1 -0
  9. package/lib/cjs/native/loader.cjs +123 -0
  10. package/lib/cjs/native/loader.cjs.map +1 -0
  11. package/lib/cjs/native/types.cjs +4 -0
  12. package/lib/cjs/native/types.cjs.map +1 -0
  13. package/lib/cjs/notifications/NotificationCenter.cjs +328 -0
  14. package/lib/cjs/notifications/NotificationCenter.cjs.map +1 -0
  15. package/lib/cjs/tray/TrayIcon.cjs +367 -0
  16. package/lib/cjs/tray/TrayIcon.cjs.map +1 -0
  17. package/lib/cjs/tray/assets.cjs +31 -0
  18. package/lib/cjs/tray/assets.cjs.map +1 -0
  19. package/lib/esm/errors.js +65 -0
  20. package/lib/esm/errors.js.map +1 -0
  21. package/lib/esm/index.js +28 -0
  22. package/lib/esm/index.js.map +1 -0
  23. package/lib/esm/native/icons.js +117 -0
  24. package/lib/esm/native/icons.js.map +1 -0
  25. package/lib/esm/native/loader.js +116 -0
  26. package/lib/esm/native/loader.js.map +1 -0
  27. package/lib/esm/native/types.js +8 -0
  28. package/lib/esm/native/types.js.map +1 -0
  29. package/lib/esm/notifications/NotificationCenter.js +322 -0
  30. package/lib/esm/notifications/NotificationCenter.js.map +1 -0
  31. package/lib/esm/tray/TrayIcon.js +362 -0
  32. package/lib/esm/tray/TrayIcon.js.map +1 -0
  33. package/lib/esm/tray/assets.js +26 -0
  34. package/lib/esm/tray/assets.js.map +1 -0
  35. package/lib/types/errors.d.cts +56 -0
  36. package/lib/types/errors.d.mts +56 -0
  37. package/lib/types/index.d.cts +27 -0
  38. package/lib/types/index.d.mts +27 -0
  39. package/lib/types/native/icons.d.cts +71 -0
  40. package/lib/types/native/icons.d.mts +71 -0
  41. package/lib/types/native/loader.d.cts +37 -0
  42. package/lib/types/native/loader.d.mts +37 -0
  43. package/lib/types/native/types.d.cts +104 -0
  44. package/lib/types/native/types.d.mts +104 -0
  45. package/lib/types/notifications/NotificationCenter.d.cts +163 -0
  46. package/lib/types/notifications/NotificationCenter.d.mts +163 -0
  47. package/lib/types/tray/TrayIcon.d.cts +174 -0
  48. package/lib/types/tray/TrayIcon.d.mts +174 -0
  49. package/lib/types/tray/assets.d.cts +25 -0
  50. package/lib/types/tray/assets.d.mts +25 -0
  51. package/native/tray-icon-node/Cargo.lock +1511 -0
  52. package/native/tray-icon-node/Cargo.toml +45 -0
  53. package/native/tray-icon-node/Cross.toml +10 -0
  54. package/native/tray-icon-node/LICENSE +21 -0
  55. package/native/tray-icon-node/UPSTREAM-README.md +281 -0
  56. package/native/tray-icon-node/UPSTREAM.md +213 -0
  57. package/native/tray-icon-node/build-manifest.json +16 -0
  58. package/native/tray-icon-node/build.rs +5 -0
  59. package/native/tray-icon-node/index.d.ts +368 -0
  60. package/native/tray-icon-node/index.js +609 -0
  61. package/native/tray-icon-node/package.json +55 -0
  62. package/native/tray-icon-node/rustfmt.toml +31 -0
  63. package/native/tray-icon-node/source-manifest.json +30 -0
  64. package/native/tray-icon-node/src/common.rs +101 -0
  65. package/native/tray-icon-node/src/icon.rs +255 -0
  66. package/native/tray-icon-node/src/lib.rs +449 -0
  67. package/native/tray-icon-node/src/menu.rs +849 -0
  68. package/native/tray-icon-node/src/tray.rs +251 -0
  69. package/native/tray-icon-node/tray-icon-node.linux-x64-gnu.node +0 -0
  70. package/package.json +131 -4
  71. package/scripts/for-os-build.mjs +60 -0
  72. package/scripts/for-os-init.mjs +327 -0
  73. package/scripts/for-os-install.mjs +47 -0
  74. package/scripts/for-os-integration.mjs +137 -0
  75. package/scripts/for-os-integrity.mjs +51 -0
  76. package/scripts/for-os-package.mjs +49 -0
  77. package/scripts/lib/native.mjs +591 -0
@@ -0,0 +1,71 @@
1
+ /**
2
+ * @module for-os.native.icons
3
+ * @description Converts TypeScript icon sources into native tray icon handles.
4
+ * @summary The native addon loads icons from file paths (or raw RGBA), so
5
+ * base64 and byte-buffer sources are materialized into a private temporary
6
+ * directory that is removed when the owning tray closes.
7
+ */
8
+ import type { NativeIconFactory } from "./types.d.mts";
9
+ /** Raw RGBA pixels accepted by {@link IconSource}. */
10
+ export type RgbaIcon = {
11
+ rgba: Buffer | Uint8Array;
12
+ width: number;
13
+ height: number;
14
+ };
15
+ /**
16
+ * Any icon representation accepted by {@link IconResolver.resolve}.
17
+ * - `string`: absolute or relative image file path
18
+ * - `{ path }`: image file path
19
+ * - `{ base64 }`: base64-encoded image bytes (PNG/JPEG, decided by `extension`)
20
+ * - `{ png }` / `{ bytes }`: raw encoded image bytes
21
+ * - `{ rgba, width, height }`: uncompressed RGBA pixels
22
+ *
23
+ * Caller-supplied `extension` values are sanitized to a safe alphanumeric/dot
24
+ * file suffix (capped at 16 characters) and fall back to `.png`.
25
+ */
26
+ export type IconSource = string | {
27
+ path: string;
28
+ } | {
29
+ base64: string;
30
+ extension?: string;
31
+ } | {
32
+ png: Buffer | Uint8Array;
33
+ } | {
34
+ bytes: Buffer | Uint8Array;
35
+ extension?: string;
36
+ } | RgbaIcon;
37
+ /**
38
+ * @description Owns the temporary directory used to materialize file-backed icons.
39
+ * @summary One resolver is normally owned by a tray or notification host and
40
+ * disposed with it. Resolving an already-native handle is intentionally not
41
+ * supported; callers pass a source and the resolver keeps the native object.
42
+ * @param {NativeIconFactory} api native icon factory used to build handles
43
+ * @param {function(string): string} [createDirectory] creates the private
44
+ * temporary directory; defaults to `fs.mkdtempSync` under the OS temp dir
45
+ * @param {function(string): void} [removeDirectory] removes the private
46
+ * directory on {@link IconResolver.dispose}; defaults to a recursive `fs.rmSync`
47
+ * @class IconResolver
48
+ */
49
+ export declare class IconResolver {
50
+ private readonly api;
51
+ private readonly createDirectory;
52
+ private readonly removeDirectory;
53
+ private directory?;
54
+ constructor(api: NativeIconFactory, createDirectory?: (prefix: string) => string, removeDirectory?: (directory: string) => void);
55
+ private ensureDirectory;
56
+ /**
57
+ * Materializes `source` into a native icon handle.
58
+ * @param {IconSource} source the icon path, bytes, base64, or RGBA data
59
+ * @return {unknown} the native icon handle expected by the addon
60
+ * @throws {IconError} when the source is invalid or points to a missing file
61
+ */
62
+ resolve(source: IconSource): unknown;
63
+ private fromPath;
64
+ private fromBytes;
65
+ /** Removes every materialized icon file; idempotent. */
66
+ dispose(): void;
67
+ /** Directory holding materialized icons, when one has been created. */
68
+ get iconDirectory(): string | undefined;
69
+ }
70
+ /** Returns a stable file extension for a path, defaulting to `.png`. */
71
+ export declare function iconExtension(path: string): string;
@@ -0,0 +1,37 @@
1
+ /**
2
+ * @module for-os.native.loader
3
+ * @description Locates and loads the vendored `tray-icon-node` NAPI-RS addon.
4
+ * @summary The addon is built from `native/tray-icon-node` by
5
+ * `scripts/for-os-install.mjs` and materialized into `node_modules/tray-icon-node`.
6
+ * Resolution order is an explicit `FOR_OS_NATIVE_MODULE` path, normal Node
7
+ * package resolution from the current project, then the crate's checked-in
8
+ * `index.js` under the current project. Loading never throws: callers decide
9
+ * whether a missing addon is fatal.
10
+ */
11
+ import type { NativeModule } from "./types.d.cts";
12
+ /** Environment variable that pins an explicit native addon module path. */
13
+ export declare const NATIVE_MODULE_ENV = "FOR_OS_NATIVE_MODULE";
14
+ /** Package name of the vendored addon. */
15
+ export declare const NATIVE_MODULE_PACKAGE = "tray-icon-node";
16
+ /** A successful or failed native-module load. */
17
+ export type NativeLoadResult = {
18
+ available: true;
19
+ api: NativeModule;
20
+ modulePath: string;
21
+ } | {
22
+ available: false;
23
+ error: Error;
24
+ };
25
+ /**
26
+ * Loads the native addon, reusing one process-wide result.
27
+ * @return {NativeLoadResult} the loaded module or the reason it is unavailable
28
+ */
29
+ export declare function loadNativeModule(): NativeLoadResult;
30
+ /**
31
+ * Loads the native addon or throws {@link NativeModuleUnavailableError}.
32
+ * @return {NativeModule} the loaded native module
33
+ * @throws {NativeModuleUnavailableError} when no usable addon was found
34
+ */
35
+ export declare function requireNativeModule(): NativeModule;
36
+ /** Clears the process-wide load cache (used by tests and re-installs). */
37
+ export declare function resetNativeModuleCache(): void;
@@ -0,0 +1,37 @@
1
+ /**
2
+ * @module for-os.native.loader
3
+ * @description Locates and loads the vendored `tray-icon-node` NAPI-RS addon.
4
+ * @summary The addon is built from `native/tray-icon-node` by
5
+ * `scripts/for-os-install.mjs` and materialized into `node_modules/tray-icon-node`.
6
+ * Resolution order is an explicit `FOR_OS_NATIVE_MODULE` path, normal Node
7
+ * package resolution from the current project, then the crate's checked-in
8
+ * `index.js` under the current project. Loading never throws: callers decide
9
+ * whether a missing addon is fatal.
10
+ */
11
+ import type { NativeModule } from "./types.d.mts";
12
+ /** Environment variable that pins an explicit native addon module path. */
13
+ export declare const NATIVE_MODULE_ENV = "FOR_OS_NATIVE_MODULE";
14
+ /** Package name of the vendored addon. */
15
+ export declare const NATIVE_MODULE_PACKAGE = "tray-icon-node";
16
+ /** A successful or failed native-module load. */
17
+ export type NativeLoadResult = {
18
+ available: true;
19
+ api: NativeModule;
20
+ modulePath: string;
21
+ } | {
22
+ available: false;
23
+ error: Error;
24
+ };
25
+ /**
26
+ * Loads the native addon, reusing one process-wide result.
27
+ * @return {NativeLoadResult} the loaded module or the reason it is unavailable
28
+ */
29
+ export declare function loadNativeModule(): NativeLoadResult;
30
+ /**
31
+ * Loads the native addon or throws {@link NativeModuleUnavailableError}.
32
+ * @return {NativeModule} the loaded native module
33
+ * @throws {NativeModuleUnavailableError} when no usable addon was found
34
+ */
35
+ export declare function requireNativeModule(): NativeModule;
36
+ /** Clears the process-wide load cache (used by tests and re-installs). */
37
+ export declare function resetNativeModuleCache(): void;
@@ -0,0 +1,104 @@
1
+ /**
2
+ * @module for-os.native.types
3
+ * @description Structural types for the vendored `tray-icon-node` NAPI-RS addon.
4
+ * @summary These mirror `native/tray-icon-node/index.d.ts` but stay deliberately
5
+ * narrow so the bridges can be exercised with a fake native module in tests.
6
+ */
7
+ /** Rectangle reported for tray-icon events. */
8
+ export type NativeRect = {
9
+ x: number;
10
+ y: number;
11
+ width: number;
12
+ height: number;
13
+ };
14
+ /** Raw tray-icon event emitted by the native event loop. */
15
+ export type NativeTrayEvent = {
16
+ eventType: string;
17
+ id: string;
18
+ x: number;
19
+ y: number;
20
+ iconRect: NativeRect;
21
+ button: number;
22
+ buttonState: number;
23
+ };
24
+ /** Menu event emitted when the user activates a menu item. */
25
+ export type NativeMenuEvent = {
26
+ id: string;
27
+ };
28
+ /** Handle to a native menu entry. */
29
+ export type NativeMenuItemHandle = {
30
+ setText(text: string): void;
31
+ setEnabled(enabled: boolean): void;
32
+ };
33
+ /** Handle to a native checkable menu entry. */
34
+ export type NativeCheckMenuItemHandle = NativeMenuItemHandle & {
35
+ isChecked(): boolean;
36
+ setChecked(checked: boolean): void;
37
+ };
38
+ /** Handle to a native menu (or submenu). */
39
+ export type NativeMenuHandle = {
40
+ appendMenuItem(item: NativeMenuItemHandle, id?: string | null): void;
41
+ appendCheckMenuItem(item: NativeCheckMenuItemHandle, id: string): void;
42
+ appendPredefinedMenuItem(item: unknown): void;
43
+ isChecked(id: string): boolean;
44
+ toggleCheck(id: string): boolean;
45
+ setText(id: string, text: string): void;
46
+ };
47
+ /** Handle to a live native tray icon. */
48
+ export type NativeTrayHost = {
49
+ setIcon(icon: unknown | null): void;
50
+ setTooltip(tooltip: string | null): void;
51
+ setTitle(title: string | null): void;
52
+ setVisible(visible: boolean): void;
53
+ };
54
+ /** Native icon factory. */
55
+ export type NativeIconFactory = {
56
+ fromPath(path: string): unknown;
57
+ fromRgba(rgba: Buffer | Uint8Array, width: number, height: number): unknown;
58
+ };
59
+ /** Native tray-icon builder. */
60
+ export type NativeTrayIconBuilder = {
61
+ withIcon(icon: unknown): NativeTrayIconBuilder;
62
+ withTooltip(tooltip: string): NativeTrayIconBuilder;
63
+ withTitle(title: string): NativeTrayIconBuilder;
64
+ withMenu(menu: NativeMenuHandle): NativeTrayIconBuilder;
65
+ build(): NativeTrayHost;
66
+ };
67
+ /** Notification action button understood by the native addon. */
68
+ export type NativeNotificationAction = {
69
+ id: string;
70
+ label: string;
71
+ };
72
+ /**
73
+ * The subset of the `tray-icon-node` module consumed by the TypeScript bridges.
74
+ * Optional members are absent on older locally built binaries.
75
+ */
76
+ export type NativeModule = {
77
+ initialize(): void;
78
+ update(): void;
79
+ Icon: NativeIconFactory;
80
+ Menu: new () => NativeMenuHandle;
81
+ MenuItemBuilder: new () => {
82
+ withText(text: string): unknown;
83
+ withEnabled(enabled: boolean): unknown;
84
+ withId(id: string): unknown;
85
+ build(): NativeMenuItemHandle;
86
+ };
87
+ CheckMenuItemBuilder?: new () => {
88
+ withText(text: string): unknown;
89
+ withEnabled(enabled: boolean): unknown;
90
+ withChecked(checked: boolean): unknown;
91
+ withId(id: string): unknown;
92
+ build(): NativeCheckMenuItemHandle;
93
+ };
94
+ PredefinedMenuItem?: {
95
+ separator(): unknown;
96
+ };
97
+ TrayIconBuilder: new () => NativeTrayIconBuilder;
98
+ pollMenuEvents(): NativeMenuEvent | null;
99
+ pollTrayEvents?(): NativeTrayEvent | null;
100
+ showNotification(title: string, body: string, timeoutMs?: number | null): void;
101
+ showNotificationWithActions?(title: string, body: string, actions: NativeNotificationAction[], timeoutMs?: number | null): void;
102
+ showAppointmentNotification?(title: string, body: string, timeoutMs?: number | null): void;
103
+ pollNotificationActions?(): string | null;
104
+ };
@@ -0,0 +1,104 @@
1
+ /**
2
+ * @module for-os.native.types
3
+ * @description Structural types for the vendored `tray-icon-node` NAPI-RS addon.
4
+ * @summary These mirror `native/tray-icon-node/index.d.ts` but stay deliberately
5
+ * narrow so the bridges can be exercised with a fake native module in tests.
6
+ */
7
+ /** Rectangle reported for tray-icon events. */
8
+ export type NativeRect = {
9
+ x: number;
10
+ y: number;
11
+ width: number;
12
+ height: number;
13
+ };
14
+ /** Raw tray-icon event emitted by the native event loop. */
15
+ export type NativeTrayEvent = {
16
+ eventType: string;
17
+ id: string;
18
+ x: number;
19
+ y: number;
20
+ iconRect: NativeRect;
21
+ button: number;
22
+ buttonState: number;
23
+ };
24
+ /** Menu event emitted when the user activates a menu item. */
25
+ export type NativeMenuEvent = {
26
+ id: string;
27
+ };
28
+ /** Handle to a native menu entry. */
29
+ export type NativeMenuItemHandle = {
30
+ setText(text: string): void;
31
+ setEnabled(enabled: boolean): void;
32
+ };
33
+ /** Handle to a native checkable menu entry. */
34
+ export type NativeCheckMenuItemHandle = NativeMenuItemHandle & {
35
+ isChecked(): boolean;
36
+ setChecked(checked: boolean): void;
37
+ };
38
+ /** Handle to a native menu (or submenu). */
39
+ export type NativeMenuHandle = {
40
+ appendMenuItem(item: NativeMenuItemHandle, id?: string | null): void;
41
+ appendCheckMenuItem(item: NativeCheckMenuItemHandle, id: string): void;
42
+ appendPredefinedMenuItem(item: unknown): void;
43
+ isChecked(id: string): boolean;
44
+ toggleCheck(id: string): boolean;
45
+ setText(id: string, text: string): void;
46
+ };
47
+ /** Handle to a live native tray icon. */
48
+ export type NativeTrayHost = {
49
+ setIcon(icon: unknown | null): void;
50
+ setTooltip(tooltip: string | null): void;
51
+ setTitle(title: string | null): void;
52
+ setVisible(visible: boolean): void;
53
+ };
54
+ /** Native icon factory. */
55
+ export type NativeIconFactory = {
56
+ fromPath(path: string): unknown;
57
+ fromRgba(rgba: Buffer | Uint8Array, width: number, height: number): unknown;
58
+ };
59
+ /** Native tray-icon builder. */
60
+ export type NativeTrayIconBuilder = {
61
+ withIcon(icon: unknown): NativeTrayIconBuilder;
62
+ withTooltip(tooltip: string): NativeTrayIconBuilder;
63
+ withTitle(title: string): NativeTrayIconBuilder;
64
+ withMenu(menu: NativeMenuHandle): NativeTrayIconBuilder;
65
+ build(): NativeTrayHost;
66
+ };
67
+ /** Notification action button understood by the native addon. */
68
+ export type NativeNotificationAction = {
69
+ id: string;
70
+ label: string;
71
+ };
72
+ /**
73
+ * The subset of the `tray-icon-node` module consumed by the TypeScript bridges.
74
+ * Optional members are absent on older locally built binaries.
75
+ */
76
+ export type NativeModule = {
77
+ initialize(): void;
78
+ update(): void;
79
+ Icon: NativeIconFactory;
80
+ Menu: new () => NativeMenuHandle;
81
+ MenuItemBuilder: new () => {
82
+ withText(text: string): unknown;
83
+ withEnabled(enabled: boolean): unknown;
84
+ withId(id: string): unknown;
85
+ build(): NativeMenuItemHandle;
86
+ };
87
+ CheckMenuItemBuilder?: new () => {
88
+ withText(text: string): unknown;
89
+ withEnabled(enabled: boolean): unknown;
90
+ withChecked(checked: boolean): unknown;
91
+ withId(id: string): unknown;
92
+ build(): NativeCheckMenuItemHandle;
93
+ };
94
+ PredefinedMenuItem?: {
95
+ separator(): unknown;
96
+ };
97
+ TrayIconBuilder: new () => NativeTrayIconBuilder;
98
+ pollMenuEvents(): NativeMenuEvent | null;
99
+ pollTrayEvents?(): NativeTrayEvent | null;
100
+ showNotification(title: string, body: string, timeoutMs?: number | null): void;
101
+ showNotificationWithActions?(title: string, body: string, actions: NativeNotificationAction[], timeoutMs?: number | null): void;
102
+ showAppointmentNotification?(title: string, body: string, timeoutMs?: number | null): void;
103
+ pollNotificationActions?(): string | null;
104
+ };
@@ -0,0 +1,163 @@
1
+ /**
2
+ * @module for-os.notifications
3
+ * @description Desktop-notification bridge with timers and JavaScript action callbacks.
4
+ * @summary `NotificationCenter` sends notifications through the native addon,
5
+ * exposes action buttons as JavaScript callbacks, and owns the auto-dismiss
6
+ * timer contract. Button delivery is native on Linux (through
7
+ * `notify-send --wait`); macOS and Windows render a plain notification and
8
+ * report that no buttons are available.
9
+ */
10
+ import type { NativeModule } from "../native/types.d.cts";
11
+ /** Default auto-dismiss delay for a notification, in milliseconds. */
12
+ export declare const DEFAULT_NOTIFICATION_TIMEOUT_MS = 10000;
13
+ /** Callback invoked when a notification action or button is activated. */
14
+ export type NotificationActionHandler = (actionId: string, notification?: NotificationRecord) => void;
15
+ /**
16
+ * One action button rendered on a notification.
17
+ * @summary Button ids match literally. The `default` action id emitted by the
18
+ * native service for a notification-body click is reserved: it resolves to the
19
+ * first button of the owning notification unless a button is explicitly named
20
+ * `default`.
21
+ */
22
+ export type NotificationButton = {
23
+ /** Stable id reported to the handler. */
24
+ id: string;
25
+ /** Button label rendered by the operating system. */
26
+ label: string;
27
+ /** Optional per-button callback. */
28
+ onClick?: NotificationActionHandler;
29
+ };
30
+ /** Reason a notification is considered dismissed. */
31
+ export type DismissReason = "timer" | "manual";
32
+ /** Public state of a dispatched notification. */
33
+ export type NotificationRecord = {
34
+ /** Stable id generated by the bridge. */
35
+ readonly id: string;
36
+ readonly title: string;
37
+ readonly body: string;
38
+ /** Configured auto-dismiss delay; `0` disables the timer. */
39
+ readonly timeoutMs: number;
40
+ /** Action buttons captured at dispatch; treat this array as read-only. */
41
+ readonly buttons: NotificationButton[];
42
+ /** Whether the operating system accepted the notification. */
43
+ readonly delivered: boolean;
44
+ /** Whether the timer or a manual call marked the notification dismissed. */
45
+ readonly dismissed: boolean;
46
+ /** Marks the notification dismissed and invokes `onDismiss` once. */
47
+ dismiss(reason?: DismissReason): void;
48
+ /** Registers an additional action handler for this notification. */
49
+ onAction(handler: NotificationActionHandler): NotificationRecord;
50
+ };
51
+ /** Options accepted by {@link NotificationCenter.notify}. */
52
+ export type NotifyOptions = {
53
+ title: string;
54
+ body: string;
55
+ /**
56
+ * Auto-dismiss delay in milliseconds. Defaults to
57
+ * {@link DEFAULT_NOTIFICATION_TIMEOUT_MS}; `0` disables the timer. The native
58
+ * host honours the delay where its notification service supports expiry
59
+ * (Linux, Windows); macOS applies the system dismissal policy while the
60
+ * bridge still tracks the timer locally.
61
+ */
62
+ timeoutMs?: number;
63
+ /** Action buttons; native delivery is Linux-only. */
64
+ buttons?: NotificationButton[];
65
+ /** Notification-level action callback. */
66
+ onAction?: NotificationActionHandler;
67
+ /** Called once when the timer fires or {@link NotificationRecord.dismiss} runs. */
68
+ onDismiss?: (reason: DismissReason, notification: NotificationRecord) => void;
69
+ };
70
+ /** Construction options for {@link NotificationCenter}. */
71
+ export type NotificationCenterOptions = {
72
+ /** Native module override (tests/embedding); defaults to the built addon. */
73
+ api?: NativeModule;
74
+ /** Global action dispatch interval (defaults to 100 ms). */
75
+ pollIntervalMs?: number;
76
+ /** Best-effort diagnostics sink. */
77
+ log?: (message: string) => void;
78
+ };
79
+ /**
80
+ * @description Sends native notifications and maps their buttons to JavaScript callbacks.
81
+ * @summary Use one centre per process. Action ids are matched against
82
+ * registered global handlers, the notification's own `onAction`, and each
83
+ * button's `onClick`. An id that matches no live notification reaches global
84
+ * handlers only, and dismissed notifications are pruned from the record set.
85
+ * The reserved `default` body-click id maps to the owning notification's first
86
+ * button. `close()` clears the timer and poll loop.
87
+ * @param {NotificationCenterOptions} [options] native module override, poll
88
+ * interval, and diagnostics sink
89
+ * @class NotificationCenter
90
+ * @example
91
+ * import { NotificationCenter } from "@decaf-ts/for-os";
92
+ * const center = new NotificationCenter();
93
+ * const notification = center.notify({
94
+ * title: "Build finished",
95
+ * body: "The native addon is ready.",
96
+ * timeoutMs: 5000,
97
+ * buttons: [{ id: "open", label: "Open" }],
98
+ * });
99
+ * notification.onAction((actionId) => console.log(actionId));
100
+ * center.close();
101
+ */
102
+ export declare class NotificationCenter {
103
+ private readonly api?;
104
+ private readonly pollIntervalMs;
105
+ private readonly log;
106
+ private readonly globalHandlers;
107
+ private readonly records;
108
+ private poll?;
109
+ private counter;
110
+ private closed;
111
+ constructor(options?: NotificationCenterOptions);
112
+ /** Whether a native notification backend is available. */
113
+ get available(): boolean;
114
+ private native;
115
+ /**
116
+ * Registers a global handler for an action id.
117
+ * @param {string} id action id
118
+ * @param {NotificationActionHandler} handler callback
119
+ * @return {NotificationCenter} this instance
120
+ */
121
+ registerAction(id: string, handler: NotificationActionHandler): this;
122
+ /**
123
+ * Removes a global action handler.
124
+ * @param {string} id action id
125
+ * @param {NotificationActionHandler} handler callback
126
+ * @return {NotificationCenter} this instance
127
+ */
128
+ unregisterAction(id: string, handler: NotificationActionHandler): this;
129
+ /**
130
+ * Sends a notification and returns its handle.
131
+ * @param {NotifyOptions} options title, body, timer, and buttons
132
+ * @return {NotificationRecord} the dispatched notification
133
+ * @throws {ValidationError} for missing title/body or invalid options
134
+ * @throws {NativeModuleUnavailableError} when no native backend is available
135
+ */
136
+ notify(options: NotifyOptions): NotificationRecord;
137
+ /**
138
+ * Sends an appointment-style notification with Accept and See buttons.
139
+ * @param {Omit<NotifyOptions, "buttons">} options notification content
140
+ * @return {NotificationRecord} the dispatched notification
141
+ */
142
+ notifyAppointment(options: Omit<NotifyOptions, "buttons">): NotificationRecord;
143
+ /**
144
+ * Drains pending native actions immediately.
145
+ * @return {string[]} action ids dispatched in this drain
146
+ */
147
+ pollActions(): string[];
148
+ /** Clears timers, the poll loop, and retained notification records. */
149
+ close(): void;
150
+ private createRecord;
151
+ private dismiss;
152
+ private removeRecord;
153
+ private dispatch;
154
+ private findRecord;
155
+ private invoke;
156
+ private startPoll;
157
+ }
158
+ /**
159
+ * Sends one notification through a short-lived default centre.
160
+ * @param {NotifyOptions} options notification content
161
+ * @return {NotificationRecord} the dispatched notification
162
+ */
163
+ export declare function notify(options: NotifyOptions): NotificationRecord;
@@ -0,0 +1,163 @@
1
+ /**
2
+ * @module for-os.notifications
3
+ * @description Desktop-notification bridge with timers and JavaScript action callbacks.
4
+ * @summary `NotificationCenter` sends notifications through the native addon,
5
+ * exposes action buttons as JavaScript callbacks, and owns the auto-dismiss
6
+ * timer contract. Button delivery is native on Linux (through
7
+ * `notify-send --wait`); macOS and Windows render a plain notification and
8
+ * report that no buttons are available.
9
+ */
10
+ import type { NativeModule } from "../native/types.d.mts";
11
+ /** Default auto-dismiss delay for a notification, in milliseconds. */
12
+ export declare const DEFAULT_NOTIFICATION_TIMEOUT_MS = 10000;
13
+ /** Callback invoked when a notification action or button is activated. */
14
+ export type NotificationActionHandler = (actionId: string, notification?: NotificationRecord) => void;
15
+ /**
16
+ * One action button rendered on a notification.
17
+ * @summary Button ids match literally. The `default` action id emitted by the
18
+ * native service for a notification-body click is reserved: it resolves to the
19
+ * first button of the owning notification unless a button is explicitly named
20
+ * `default`.
21
+ */
22
+ export type NotificationButton = {
23
+ /** Stable id reported to the handler. */
24
+ id: string;
25
+ /** Button label rendered by the operating system. */
26
+ label: string;
27
+ /** Optional per-button callback. */
28
+ onClick?: NotificationActionHandler;
29
+ };
30
+ /** Reason a notification is considered dismissed. */
31
+ export type DismissReason = "timer" | "manual";
32
+ /** Public state of a dispatched notification. */
33
+ export type NotificationRecord = {
34
+ /** Stable id generated by the bridge. */
35
+ readonly id: string;
36
+ readonly title: string;
37
+ readonly body: string;
38
+ /** Configured auto-dismiss delay; `0` disables the timer. */
39
+ readonly timeoutMs: number;
40
+ /** Action buttons captured at dispatch; treat this array as read-only. */
41
+ readonly buttons: NotificationButton[];
42
+ /** Whether the operating system accepted the notification. */
43
+ readonly delivered: boolean;
44
+ /** Whether the timer or a manual call marked the notification dismissed. */
45
+ readonly dismissed: boolean;
46
+ /** Marks the notification dismissed and invokes `onDismiss` once. */
47
+ dismiss(reason?: DismissReason): void;
48
+ /** Registers an additional action handler for this notification. */
49
+ onAction(handler: NotificationActionHandler): NotificationRecord;
50
+ };
51
+ /** Options accepted by {@link NotificationCenter.notify}. */
52
+ export type NotifyOptions = {
53
+ title: string;
54
+ body: string;
55
+ /**
56
+ * Auto-dismiss delay in milliseconds. Defaults to
57
+ * {@link DEFAULT_NOTIFICATION_TIMEOUT_MS}; `0` disables the timer. The native
58
+ * host honours the delay where its notification service supports expiry
59
+ * (Linux, Windows); macOS applies the system dismissal policy while the
60
+ * bridge still tracks the timer locally.
61
+ */
62
+ timeoutMs?: number;
63
+ /** Action buttons; native delivery is Linux-only. */
64
+ buttons?: NotificationButton[];
65
+ /** Notification-level action callback. */
66
+ onAction?: NotificationActionHandler;
67
+ /** Called once when the timer fires or {@link NotificationRecord.dismiss} runs. */
68
+ onDismiss?: (reason: DismissReason, notification: NotificationRecord) => void;
69
+ };
70
+ /** Construction options for {@link NotificationCenter}. */
71
+ export type NotificationCenterOptions = {
72
+ /** Native module override (tests/embedding); defaults to the built addon. */
73
+ api?: NativeModule;
74
+ /** Global action dispatch interval (defaults to 100 ms). */
75
+ pollIntervalMs?: number;
76
+ /** Best-effort diagnostics sink. */
77
+ log?: (message: string) => void;
78
+ };
79
+ /**
80
+ * @description Sends native notifications and maps their buttons to JavaScript callbacks.
81
+ * @summary Use one centre per process. Action ids are matched against
82
+ * registered global handlers, the notification's own `onAction`, and each
83
+ * button's `onClick`. An id that matches no live notification reaches global
84
+ * handlers only, and dismissed notifications are pruned from the record set.
85
+ * The reserved `default` body-click id maps to the owning notification's first
86
+ * button. `close()` clears the timer and poll loop.
87
+ * @param {NotificationCenterOptions} [options] native module override, poll
88
+ * interval, and diagnostics sink
89
+ * @class NotificationCenter
90
+ * @example
91
+ * import { NotificationCenter } from "@decaf-ts/for-os";
92
+ * const center = new NotificationCenter();
93
+ * const notification = center.notify({
94
+ * title: "Build finished",
95
+ * body: "The native addon is ready.",
96
+ * timeoutMs: 5000,
97
+ * buttons: [{ id: "open", label: "Open" }],
98
+ * });
99
+ * notification.onAction((actionId) => console.log(actionId));
100
+ * center.close();
101
+ */
102
+ export declare class NotificationCenter {
103
+ private readonly api?;
104
+ private readonly pollIntervalMs;
105
+ private readonly log;
106
+ private readonly globalHandlers;
107
+ private readonly records;
108
+ private poll?;
109
+ private counter;
110
+ private closed;
111
+ constructor(options?: NotificationCenterOptions);
112
+ /** Whether a native notification backend is available. */
113
+ get available(): boolean;
114
+ private native;
115
+ /**
116
+ * Registers a global handler for an action id.
117
+ * @param {string} id action id
118
+ * @param {NotificationActionHandler} handler callback
119
+ * @return {NotificationCenter} this instance
120
+ */
121
+ registerAction(id: string, handler: NotificationActionHandler): this;
122
+ /**
123
+ * Removes a global action handler.
124
+ * @param {string} id action id
125
+ * @param {NotificationActionHandler} handler callback
126
+ * @return {NotificationCenter} this instance
127
+ */
128
+ unregisterAction(id: string, handler: NotificationActionHandler): this;
129
+ /**
130
+ * Sends a notification and returns its handle.
131
+ * @param {NotifyOptions} options title, body, timer, and buttons
132
+ * @return {NotificationRecord} the dispatched notification
133
+ * @throws {ValidationError} for missing title/body or invalid options
134
+ * @throws {NativeModuleUnavailableError} when no native backend is available
135
+ */
136
+ notify(options: NotifyOptions): NotificationRecord;
137
+ /**
138
+ * Sends an appointment-style notification with Accept and See buttons.
139
+ * @param {Omit<NotifyOptions, "buttons">} options notification content
140
+ * @return {NotificationRecord} the dispatched notification
141
+ */
142
+ notifyAppointment(options: Omit<NotifyOptions, "buttons">): NotificationRecord;
143
+ /**
144
+ * Drains pending native actions immediately.
145
+ * @return {string[]} action ids dispatched in this drain
146
+ */
147
+ pollActions(): string[];
148
+ /** Clears timers, the poll loop, and retained notification records. */
149
+ close(): void;
150
+ private createRecord;
151
+ private dismiss;
152
+ private removeRecord;
153
+ private dispatch;
154
+ private findRecord;
155
+ private invoke;
156
+ private startPoll;
157
+ }
158
+ /**
159
+ * Sends one notification through a short-lived default centre.
160
+ * @param {NotifyOptions} options notification content
161
+ * @return {NotificationRecord} the dispatched notification
162
+ */
163
+ export declare function notify(options: NotifyOptions): NotificationRecord;