active-window-sessions 0.0.0-stage → 0.1.0
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.
- package/CHANGELOG.md +10 -0
- package/LICENSE +21 -0
- package/README.md +215 -2
- package/dist/aggregate.d.ts +6 -0
- package/dist/aggregate.js +29 -0
- package/dist/engine.d.ts +31 -0
- package/dist/engine.js +170 -0
- package/dist/host.d.ts +11 -0
- package/dist/host.js +22 -0
- package/dist/ignore.d.ts +8 -0
- package/dist/ignore.js +43 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.js +7 -0
- package/dist/macos.d.ts +118 -0
- package/dist/macos.js +218 -0
- package/dist/platform.d.ts +25 -0
- package/dist/platform.js +53 -0
- package/dist/sessionize.d.ts +6 -0
- package/dist/sessionize.js +15 -0
- package/dist/tracker.d.ts +8 -0
- package/dist/tracker.js +130 -0
- package/dist/types.d.ts +132 -0
- package/dist/types.js +1 -0
- package/dist/windows.d.ts +29 -0
- package/dist/windows.js +99 -0
- package/package.json +75 -4
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
/** What is in front of the user at one moment. */
|
|
2
|
+
export interface WindowInfo {
|
|
3
|
+
/** Display name of the application, such as "Google Chrome". */
|
|
4
|
+
app: string;
|
|
5
|
+
/** Stable identifier: macOS bundle id, Windows exe file name or Linux process name. Falls back to `app`. */
|
|
6
|
+
appId?: string;
|
|
7
|
+
/** Window title. Used only by `ignore` predicates; it is never stored in a segment. */
|
|
8
|
+
title?: string;
|
|
9
|
+
/** URL of the active tab when the window is a browser that reports one. */
|
|
10
|
+
url?: string;
|
|
11
|
+
}
|
|
12
|
+
/** One reading of the active window at a timestamp, plus how long the user had been idle. */
|
|
13
|
+
export interface Sample {
|
|
14
|
+
/** Time of the reading, in milliseconds since the Unix epoch. */
|
|
15
|
+
at: number;
|
|
16
|
+
/** The active window, or `null`/`undefined` when nothing could be read. */
|
|
17
|
+
window?: WindowInfo | null;
|
|
18
|
+
/** Seconds since the last keyboard or mouse input, when known. */
|
|
19
|
+
idleSeconds?: number | null;
|
|
20
|
+
}
|
|
21
|
+
/** A continuous stretch of time spent in one app (and, for browsers, on one website). */
|
|
22
|
+
export interface Segment {
|
|
23
|
+
/** Display name of the app. */
|
|
24
|
+
app: string;
|
|
25
|
+
/** Stable app identifier (see `WindowInfo.appId`). */
|
|
26
|
+
appId: string;
|
|
27
|
+
/** Lower-case host of the active tab, such as "github.com". Only set for http(s) URLs. */
|
|
28
|
+
host?: string;
|
|
29
|
+
/** Full URL without the fragment. Only set when the `urls` option is `'full'`. */
|
|
30
|
+
url?: string;
|
|
31
|
+
/** Start time, in milliseconds since the Unix epoch. */
|
|
32
|
+
startMs: number;
|
|
33
|
+
/** End time, in milliseconds since the Unix epoch. */
|
|
34
|
+
endMs: number;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* A rule for windows that should not count as an app. A string matches `appId` or `app` exactly,
|
|
38
|
+
* a RegExp is tested against both, and a function receives the whole window.
|
|
39
|
+
*/
|
|
40
|
+
export type IgnoreRule = string | RegExp | ((window: WindowInfo) => boolean);
|
|
41
|
+
/** What to keep of a browser URL: the host (default), the full URL, or nothing. */
|
|
42
|
+
export type UrlMode = 'host' | 'full' | 'none';
|
|
43
|
+
/** Options shared by `sessionize` and `createTracker`. */
|
|
44
|
+
export interface SegmentationOptions {
|
|
45
|
+
/** Same-target segments closer together than this are merged into one. Default 2000. */
|
|
46
|
+
mergeGapMs?: number;
|
|
47
|
+
/** Segments shorter than this are dropped. Default 1000. */
|
|
48
|
+
minSegmentMs?: number;
|
|
49
|
+
/** An open segment ends at the last sighting once no window has been seen for this long. Default 10000. */
|
|
50
|
+
staleAfterMs?: number;
|
|
51
|
+
/** A gap between samples longer than this (sleep, a frozen process) ends the open segment at the last sighting. Default 60000. */
|
|
52
|
+
maxSampleGapMs?: number;
|
|
53
|
+
/** Idle seconds at which the open segment is cut at the last input. Default 50. */
|
|
54
|
+
idleAfterSeconds?: number;
|
|
55
|
+
/** Windows to ignore, such as system UI. Replaces `DEFAULT_IGNORE` when given. */
|
|
56
|
+
ignore?: readonly IgnoreRule[];
|
|
57
|
+
/** What to keep of browser URLs. Default `'host'`. */
|
|
58
|
+
urls?: UrlMode;
|
|
59
|
+
}
|
|
60
|
+
/** Options for `sessionize`. */
|
|
61
|
+
export interface SessionizeOptions extends SegmentationOptions {
|
|
62
|
+
/** End the last open segment at this time instead of at the last sample. */
|
|
63
|
+
endAt?: number;
|
|
64
|
+
}
|
|
65
|
+
/** Time source for the tracker. Pass a fake in tests. */
|
|
66
|
+
export interface Clock {
|
|
67
|
+
/** Current time in milliseconds since the Unix epoch. */
|
|
68
|
+
now(): number;
|
|
69
|
+
setTimeout(callback: () => void, ms: number): unknown;
|
|
70
|
+
clearTimeout(handle: unknown): void;
|
|
71
|
+
setInterval(callback: () => void, ms: number): unknown;
|
|
72
|
+
clearInterval(handle: unknown): void;
|
|
73
|
+
}
|
|
74
|
+
/** Reads the active window once. Resolve `null` when there is none. */
|
|
75
|
+
export type WindowSampler = () => WindowInfo | null | undefined | Promise<WindowInfo | null | undefined>;
|
|
76
|
+
/** Reads seconds since the last input, or `null` when unknown. For example `() => powerMonitor.getSystemIdleTime()`. */
|
|
77
|
+
export type IdleSource = () => number | null | undefined | Promise<number | null | undefined>;
|
|
78
|
+
/** Options for `createTracker`. */
|
|
79
|
+
export interface TrackerOptions extends SegmentationOptions {
|
|
80
|
+
/** Reads the active window, for example the result of `getWindowsSampler()`. */
|
|
81
|
+
sample: WindowSampler;
|
|
82
|
+
/** Reads idle seconds. Without it, idle time is not considered. */
|
|
83
|
+
getIdleSeconds?: IdleSource;
|
|
84
|
+
/** Time between polls. Default 2000. */
|
|
85
|
+
intervalMs?: number;
|
|
86
|
+
/** A `sample` call that takes longer than this counts as no window. Default 4000. */
|
|
87
|
+
sampleTimeoutMs?: number;
|
|
88
|
+
/** Receives finished segments, oldest first. Never called with an empty list. */
|
|
89
|
+
onSegments: (segments: Segment[]) => void;
|
|
90
|
+
/** Receives errors from `sample`, `getIdleSeconds` and `onSegments`. Without it they are ignored. */
|
|
91
|
+
onError?: (error: unknown) => void;
|
|
92
|
+
/** Time source. Defaults to the system clock. */
|
|
93
|
+
clock?: Clock;
|
|
94
|
+
}
|
|
95
|
+
/** Options for `Tracker.flush`. */
|
|
96
|
+
export interface FlushOptions {
|
|
97
|
+
/** Also end the open segment now and continue it from this moment. */
|
|
98
|
+
cut?: boolean;
|
|
99
|
+
}
|
|
100
|
+
/** A running (or stopped) poller. */
|
|
101
|
+
export interface Tracker {
|
|
102
|
+
/** Starts polling and takes the first sample immediately. Does nothing when already running. */
|
|
103
|
+
start(): void;
|
|
104
|
+
/** Stops polling and delivers every pending segment, ending the open one at `endMs` (default now). */
|
|
105
|
+
stop(endMs?: number): Segment[];
|
|
106
|
+
/** Delivers segments that are held back for merging and, with `cut`, the open one. */
|
|
107
|
+
flush(options?: FlushOptions): Segment[];
|
|
108
|
+
/** Whether the tracker is polling. */
|
|
109
|
+
isRunning(): boolean;
|
|
110
|
+
}
|
|
111
|
+
/** How `aggregate` groups segments. */
|
|
112
|
+
export type AggregateBy = 'app' | 'host';
|
|
113
|
+
/** Options for `aggregate`. */
|
|
114
|
+
export interface AggregateOptions {
|
|
115
|
+
/** Group by app (`appId`) or by website host. Segments without a host are skipped for `'host'`. */
|
|
116
|
+
by: AggregateBy;
|
|
117
|
+
/** Count only time at or after this moment (milliseconds since the Unix epoch). */
|
|
118
|
+
from?: number;
|
|
119
|
+
/** Count only time before or at this moment (milliseconds since the Unix epoch). */
|
|
120
|
+
to?: number;
|
|
121
|
+
}
|
|
122
|
+
/** Total time for one app or host. */
|
|
123
|
+
export interface UsageTotal {
|
|
124
|
+
/** `appId` when grouped by app, the host when grouped by host. */
|
|
125
|
+
key: string;
|
|
126
|
+
/** Display name: the app name, or the host. */
|
|
127
|
+
name: string;
|
|
128
|
+
/** Total time in milliseconds, after clipping to `from`/`to`. */
|
|
129
|
+
durationMs: number;
|
|
130
|
+
/** Number of segments that contributed time. */
|
|
131
|
+
segmentCount: number;
|
|
132
|
+
}
|
package/dist/types.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import type { WindowInfo } from './types.ts';
|
|
2
|
+
/** A permission flag for get-windows on macOS: a fixed value, or a function read before every poll. */
|
|
3
|
+
export type PermissionFlag = boolean | (() => boolean);
|
|
4
|
+
/** Options for `getWindowsSampler`. */
|
|
5
|
+
export interface WindowsSamplerOptions {
|
|
6
|
+
/**
|
|
7
|
+
* Read the URL of browser tabs (macOS). When `false`, Accessibility is not requested from
|
|
8
|
+
* get-windows, so it neither reads URLs nor triggers a browser Automation prompt. Default `true`.
|
|
9
|
+
*/
|
|
10
|
+
urls?: boolean;
|
|
11
|
+
/** Overrides get-windows' `accessibilityPermission` option (macOS). Wins over `urls`. */
|
|
12
|
+
accessibilityPermission?: PermissionFlag;
|
|
13
|
+
/** Overrides get-windows' `screenRecordingPermission` option (macOS). */
|
|
14
|
+
screenRecordingPermission?: PermissionFlag;
|
|
15
|
+
/** Platform to assume. Defaults to `process.platform`. get-windows options are only passed on `'darwin'`. */
|
|
16
|
+
platform?: string;
|
|
17
|
+
/** Loads the get-windows module. Defaults to a lazy `import('get-windows')`. Useful in tests. */
|
|
18
|
+
loadModule?: () => Promise<unknown>;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Converts a get-windows (or active-win) result into a `WindowInfo`, or `null` when it has no
|
|
22
|
+
* owning app. `appId` is the macOS bundle id, else the executable file name, else the app name.
|
|
23
|
+
*/
|
|
24
|
+
export declare function toWindowInfo(result: unknown): WindowInfo | null;
|
|
25
|
+
/**
|
|
26
|
+
* A `sample` function backed by get-windows, which is loaded on first use. Pass it to `createTracker`.
|
|
27
|
+
* get-windows is an optional peer dependency; the sampler throws a clear error when it is missing.
|
|
28
|
+
*/
|
|
29
|
+
export declare function getWindowsSampler(options?: WindowsSamplerOptions): () => Promise<WindowInfo | null>;
|
package/dist/windows.js
ADDED
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
|
|
2
|
+
if (typeof path === "string" && /^\.\.?\//.test(path)) {
|
|
3
|
+
return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
|
|
4
|
+
return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
|
|
5
|
+
});
|
|
6
|
+
}
|
|
7
|
+
return path;
|
|
8
|
+
};
|
|
9
|
+
const MISSING_MESSAGE = 'active-window-sessions: the "get-windows" package could not be loaded. Install it with: npm install get-windows';
|
|
10
|
+
async function defaultLoad() {
|
|
11
|
+
// A variable specifier keeps get-windows out of type checking and bundler graphs: it is an optional peer.
|
|
12
|
+
const specifier = 'get-windows';
|
|
13
|
+
try {
|
|
14
|
+
return (await import(__rewriteRelativeImportExtension(specifier)));
|
|
15
|
+
}
|
|
16
|
+
catch (cause) {
|
|
17
|
+
throw new Error(MISSING_MESSAGE, { cause });
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
function isRecord(value) {
|
|
21
|
+
return typeof value === 'object' && value !== null;
|
|
22
|
+
}
|
|
23
|
+
function resolveActiveWindow(mod) {
|
|
24
|
+
if (typeof mod === 'function')
|
|
25
|
+
return mod;
|
|
26
|
+
if (!isRecord(mod))
|
|
27
|
+
return null;
|
|
28
|
+
if (typeof mod.activeWindow === 'function')
|
|
29
|
+
return mod.activeWindow;
|
|
30
|
+
if (typeof mod.default === 'function')
|
|
31
|
+
return mod.default;
|
|
32
|
+
if (isRecord(mod.default) && typeof mod.default.activeWindow === 'function') {
|
|
33
|
+
return mod.default.activeWindow;
|
|
34
|
+
}
|
|
35
|
+
return null;
|
|
36
|
+
}
|
|
37
|
+
function fileName(path) {
|
|
38
|
+
return path.split(/[\\/]/).filter(Boolean).at(-1) ?? '';
|
|
39
|
+
}
|
|
40
|
+
function text(value) {
|
|
41
|
+
return typeof value === 'string' ? value.trim() : '';
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Converts a get-windows (or active-win) result into a `WindowInfo`, or `null` when it has no
|
|
45
|
+
* owning app. `appId` is the macOS bundle id, else the executable file name, else the app name.
|
|
46
|
+
*/
|
|
47
|
+
export function toWindowInfo(result) {
|
|
48
|
+
if (!isRecord(result) || !isRecord(result.owner))
|
|
49
|
+
return null;
|
|
50
|
+
const owner = result.owner;
|
|
51
|
+
const name = text(owner.name);
|
|
52
|
+
const appId = text(owner.bundleId) || fileName(text(owner.path)) || name;
|
|
53
|
+
const app = name || appId;
|
|
54
|
+
if (!app)
|
|
55
|
+
return null;
|
|
56
|
+
return {
|
|
57
|
+
app,
|
|
58
|
+
appId,
|
|
59
|
+
title: typeof result.title === 'string' ? result.title : '',
|
|
60
|
+
...(typeof result.url === 'string' && result.url ? { url: result.url } : {}),
|
|
61
|
+
};
|
|
62
|
+
}
|
|
63
|
+
const read = (flag) => (typeof flag === 'function' ? flag() : flag);
|
|
64
|
+
/**
|
|
65
|
+
* A `sample` function backed by get-windows, which is loaded on first use. Pass it to `createTracker`.
|
|
66
|
+
* get-windows is an optional peer dependency; the sampler throws a clear error when it is missing.
|
|
67
|
+
*/
|
|
68
|
+
export function getWindowsSampler(options = {}) {
|
|
69
|
+
const load = options.loadModule ?? defaultLoad;
|
|
70
|
+
const platform = options.platform ?? process.platform;
|
|
71
|
+
let loading = null;
|
|
72
|
+
const getFunction = () => {
|
|
73
|
+
loading ??= load().then((mod) => {
|
|
74
|
+
const fn = resolveActiveWindow(mod);
|
|
75
|
+
if (!fn)
|
|
76
|
+
throw new Error('active-window-sessions: get-windows does not export an activeWindow function');
|
|
77
|
+
return fn;
|
|
78
|
+
});
|
|
79
|
+
// A failed load is not cached, so installing the package later works without a restart.
|
|
80
|
+
loading.catch(() => {
|
|
81
|
+
loading = null;
|
|
82
|
+
});
|
|
83
|
+
return loading;
|
|
84
|
+
};
|
|
85
|
+
const callOptions = () => {
|
|
86
|
+
if (platform !== 'darwin')
|
|
87
|
+
return undefined;
|
|
88
|
+
const out = {};
|
|
89
|
+
if (options.accessibilityPermission !== undefined)
|
|
90
|
+
out.accessibilityPermission = read(options.accessibilityPermission);
|
|
91
|
+
else if (options.urls === false)
|
|
92
|
+
out.accessibilityPermission = false;
|
|
93
|
+
if (options.screenRecordingPermission !== undefined) {
|
|
94
|
+
out.screenRecordingPermission = read(options.screenRecordingPermission);
|
|
95
|
+
}
|
|
96
|
+
return Object.keys(out).length > 0 ? out : undefined;
|
|
97
|
+
};
|
|
98
|
+
return async () => toWindowInfo(await (await getFunction())(callOptions()));
|
|
99
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,77 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "active-window-sessions",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Turn active-window polling into clean time segments per app and per website: merges short gaps, drops blips, respects idle time, ignores system UI and aggregates totals.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"active-window",
|
|
7
|
+
"active-win",
|
|
8
|
+
"get-windows",
|
|
9
|
+
"time-tracking",
|
|
10
|
+
"app-usage",
|
|
11
|
+
"screen-time",
|
|
12
|
+
"activity-tracking",
|
|
13
|
+
"idle",
|
|
14
|
+
"sessions",
|
|
15
|
+
"electron"
|
|
16
|
+
],
|
|
17
|
+
"homepage": "https://github.com/saimulft/active-window-sessions#readme",
|
|
18
|
+
"bugs": {
|
|
19
|
+
"url": "https://github.com/saimulft/active-window-sessions/issues"
|
|
20
|
+
},
|
|
21
|
+
"repository": {
|
|
22
|
+
"type": "git",
|
|
23
|
+
"url": "git+https://github.com/saimulft/active-window-sessions.git"
|
|
24
|
+
},
|
|
25
|
+
"license": "MIT",
|
|
26
|
+
"author": "Saimul Islam (https://github.com/saimulft)",
|
|
27
|
+
"type": "module",
|
|
28
|
+
"exports": {
|
|
29
|
+
".": {
|
|
30
|
+
"types": "./dist/index.d.ts",
|
|
31
|
+
"default": "./dist/index.js"
|
|
32
|
+
},
|
|
33
|
+
"./macos": {
|
|
34
|
+
"types": "./dist/macos.d.ts",
|
|
35
|
+
"default": "./dist/macos.js"
|
|
36
|
+
},
|
|
37
|
+
"./package.json": "./package.json"
|
|
38
|
+
},
|
|
39
|
+
"main": "./dist/index.js",
|
|
40
|
+
"types": "./dist/index.d.ts",
|
|
41
|
+
"files": [
|
|
42
|
+
"dist",
|
|
43
|
+
"CHANGELOG.md"
|
|
44
|
+
],
|
|
45
|
+
"sideEffects": false,
|
|
46
|
+
"engines": {
|
|
47
|
+
"node": ">=20"
|
|
48
|
+
},
|
|
49
|
+
"scripts": {
|
|
50
|
+
"build": "rm -rf dist && tsc -p tsconfig.build.json",
|
|
51
|
+
"lint": "eslint . && npm run lint:names",
|
|
52
|
+
"lint:names": "ls-lint",
|
|
53
|
+
"typecheck": "tsc --noEmit",
|
|
54
|
+
"format": "prettier --write .",
|
|
55
|
+
"format:check": "prettier --check .",
|
|
56
|
+
"test": "node --test \"test/**/*.test.ts\"",
|
|
57
|
+
"prepublishOnly": "npm run lint && npm run typecheck && npm test && npm run build"
|
|
58
|
+
},
|
|
59
|
+
"peerDependencies": {
|
|
60
|
+
"get-windows": ">=9"
|
|
61
|
+
},
|
|
62
|
+
"peerDependenciesMeta": {
|
|
63
|
+
"get-windows": {
|
|
64
|
+
"optional": true
|
|
65
|
+
}
|
|
66
|
+
},
|
|
67
|
+
"devDependencies": {
|
|
68
|
+
"@eslint/js": "^10.0.1",
|
|
69
|
+
"@ls-lint/ls-lint": "^2.3.2",
|
|
70
|
+
"@types/node": "^20.19.43",
|
|
71
|
+
"eslint": "^10.15.0",
|
|
72
|
+
"globals": "^17.14.0",
|
|
73
|
+
"prettier": "^3.10.1",
|
|
74
|
+
"typescript": "^6.0.3",
|
|
75
|
+
"typescript-eslint": "^8.73.0"
|
|
76
|
+
}
|
|
77
|
+
}
|