@chronicle.app/timing-app 0.3.0

package/dist/connectors/TimingDbExtractor.js

@@ -0,0 +1,121 @@
+import { SqliteExtractor } from '@chronicle.app/etl-sqlite';
+import { z } from 'zod';
+export const DEFAULT_DB = `${process.env.HOME}/Library/Application Support/info.eurocomp.Timing2/SQLite.db`;
+export const DEFAULT_WINDOW_DAYS = 90;
+/**
+ * Shared base for the extractors that read Timing.app's local SQLite: opens the
+ * DB read-only, pre-loads the small `Device`/`Project` lookups, and resolves the
+ * time window. `AppActivity` (6M+ rows) is streamed with a cursor by subclasses.
+ */
+export class TimingDbExtractor extends SqliteExtractor {
+    static delivery = 'local';
+    static strategy = 'app-db';
+    static temporality = 'event';
+    static schema = SqliteExtractor.schema.omit({ input: true }).extend({
+        input: z.string().describe("Path to Timing.app's SQLite.db").default(DEFAULT_DB),
+        all: z
+            .boolean()
+            .default(false)
+            .describe(`Import the full history instead of the last ${DEFAULT_WINDOW_DAYS} days`),
+    });
+    /**
+     * Lower bound (epoch seconds): explicit `since`, else a default window, else
+     * none. An unbounded `--limit 0` also drops the window — asking for "no cap"
+     * is a request for a full backfill, not the newest 90 days without a count cap.
+     */
+    sinceSeconds() {
+        if (this.config.since)
+            return this.config.since.getTime() / 1000;
+        if (this.config.all || this.getEffectiveLimit() === null)
+            return null;
+        return (Date.now() - DEFAULT_WINDOW_DAYS * 86_400_000) / 1000;
+    }
+    untilSeconds() {
+        return this.config.until ? this.config.until.getTime() / 1000 : null;
+    }
+    loadDevices() {
+        const rows = this.db.prepare(`SELECT CAST(localID AS TEXT) AS localId, CAST(globalID AS TEXT) AS globalId,
+              macAddress, displayName, property_bag AS propertyBag
+       FROM Device`).all();
+        const devices = new Map();
+        for (const row of rows) {
+            const bag = parseBag(row.propertyBag);
+            const relayed = bag._imported_via_screen_time === true;
+            const mac = !relayed && row.macAddress instanceof Uint8Array && row.macAddress.length === 6
+                ? formatMac(row.macAddress)
+                : null;
+            devices.set(row.localId, {
+                globalId: row.globalId,
+                name: bag._display_name_override || row.displayName || row.globalId,
+                mac,
+                model: bag._device_model ?? null,
+            });
+        }
+        return devices;
+    }
+    loadProjects() {
+        const rows = this.db.prepare(`SELECT CAST(id AS TEXT) AS id, title, CAST(parentID AS TEXT) AS parentId,
+              color, productivityScore, isArchived, property_bag AS propertyBag
+       FROM Project WHERE isSample = 0`).all();
+        const projects = new Map();
+        for (const row of rows) {
+            const bag = parseBag(row.propertyBag);
+            projects.set(row.id, {
+                id: row.id,
+                title: row.title,
+                parentId: row.parentId ?? null,
+                color: row.color ?? null,
+                isArchived: Boolean(row.isArchived),
+                billing: bag._default_billing_status ?? null,
+            });
+        }
+        return projects;
+    }
+    /** A resolver that nests a project's full ancestry (leaf-first) for a row. */
+    projectChainResolver() {
+        const projects = this.loadProjects();
+        return (id) => resolveChain(projects, id);
+    }
+    countWindow(table, col, extra = '') {
+        const since = this.sinceSeconds();
+        const until = this.untilSeconds();
+        const conditions = ['isDeleted = 0'];
+        const params = [];
+        if (since !== null) {
+            conditions.push(`${col} > ?`);
+            params.push(since);
+        }
+        if (until !== null) {
+            conditions.push(`${col} < ?`);
+            params.push(until);
+        }
+        const where = conditions.join(' AND ') + extra;
+        return this.db.prepare(`SELECT COUNT(*) AS n FROM ${table} WHERE ${where}`).get(...params).n;
+    }
+}
+/** A project's ancestry, leaf-first: [self, parent, grandparent, ...]. */
+export function resolveChain(projects, id) {
+    const chain = [];
+    const seen = new Set();
+    let cur = id;
+    while (cur && projects.has(cur) && !seen.has(cur)) {
+        seen.add(cur);
+        const p = projects.get(cur);
+        chain.push({ id: p.id, title: p.title });
+        cur = p.parentId;
+    }
+    return chain;
+}
+function formatMac(buf) {
+    return [...buf].map(b => b.toString(16).padStart(2, '0')).join(':');
+}
+function parseBag(value) {
+    if (typeof value !== 'string' || !value)
+        return {};
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return {};
+    }
+}

package/dist/connectors/TimingDefaultExtractor.d.ts

@@ -0,0 +1,25 @@
+import { MergingExtractor, Record } from '@chronicle.app/etl';
+import { AppUsageExtractor } from './AppUsageExtractor.js';
+import { TimeEntriesExtractor } from './TimeEntriesExtractor.js';
+import { TimingCallExtractor } from './TimingCallExtractor.js';
+import TimingDefaultTransformer from './TimingDefaultTransformer.js';
+/**
+ * The default `timing-app` extractor: a reverse-chronological merge of the
+ * curated core streams — app usage, time entries, and calls. `--limit` applies
+ * to the merged output, so `-l 1` yields the single most-recent record across
+ * all three. Focused extractors remain available individually via `-t`.
+ */
+export declare class TimingDefaultExtractor extends MergingExtractor<typeof TimingDefaultExtractor> {
+    static source: string;
+    static description: string;
+    static delivery: "local";
+    static strategy: string;
+    static recordTypes: string[];
+    static default: boolean;
+    static defaultTransformer: typeof TimingDefaultTransformer;
+    static children: (typeof AppUsageExtractor | typeof TimeEntriesExtractor | typeof TimingCallExtractor)[];
+    static schema: any;
+    /** Calls key their occurrence on `startSec`; activity/entries on `startDate`. */
+    protected sortKey(record: Record): number;
+}
+//# sourceMappingURL=TimingDefaultExtractor.d.ts.map

package/dist/connectors/TimingDefaultExtractor.js

@@ -0,0 +1,37 @@
+import { MergingExtractor } from '@chronicle.app/etl';
+import { z } from 'zod';
+import { AppUsageExtractor } from './AppUsageExtractor.js';
+import { TimeEntriesExtractor } from './TimeEntriesExtractor.js';
+import { TimingCallExtractor } from './TimingCallExtractor.js';
+import TimingDefaultTransformer from './TimingDefaultTransformer.js';
+import { DEFAULT_DB, DEFAULT_WINDOW_DAYS } from './TimingDbExtractor.js';
+/**
+ * The default `timing-app` extractor: a reverse-chronological merge of the
+ * curated core streams — app usage, time entries, and calls. `--limit` applies
+ * to the merged output, so `-l 1` yields the single most-recent record across
+ * all three. Focused extractors remain available individually via `-t`.
+ */
+export class TimingDefaultExtractor extends MergingExtractor {
+    static source = 'timing-app';
+    static description = 'Everything: app usage, time entries, and calls';
+    static delivery = 'local';
+    static strategy = 'app-db';
+    static recordTypes = ['app-activities', 'time-entries', 'calls'];
+    static default = true;
+    static defaultTransformer = TimingDefaultTransformer;
+    static children = [AppUsageExtractor, TimeEntriesExtractor, TimingCallExtractor];
+    // Superset of the children's flags, so RunnerBuilder passes them through to
+    // the merge, which forwards the raw config to each child.
+    static schema = MergingExtractor.schema.extend({
+        input: z.string().describe("Path to Timing.app's SQLite.db").default(DEFAULT_DB),
+        all: z
+            .boolean()
+            .default(false)
+            .describe(`Import the full history instead of the last ${DEFAULT_WINDOW_DAYS} days`),
+    });
+    /** Calls key their occurrence on `startSec`; activity/entries on `startDate`. */
+    sortKey(record) {
+        const ctx = record.context;
+        return record.extraction.recordType === 'calls' ? (ctx.startSec ?? 0) : (ctx.startDate ?? 0);
+    }
+}

package/dist/connectors/TimingDefaultTransformer.d.ts

@@ -0,0 +1,17 @@
+import { DispatchingTransformer } from '@chronicle.app/etl';
+import TimingAppTransformer from './TimingAppTransformer.js';
+import TimingCallTransformer from './TimingCallTransformer.js';
+/**
+ * Routes the merged default stream to the focused transformers by record type:
+ * app usage and time entries → `TimingAppTransformer` (source `timing-app`),
+ * calls → `TimingCallTransformer` (re-sourced to `apple-call-history` so they fold with
+ * the Apple Call History plugin).
+ */
+export default class TimingDefaultTransformer extends DispatchingTransformer {
+    static routes: {
+        'app-activities': typeof TimingAppTransformer;
+        'time-entries': typeof TimingAppTransformer;
+        calls: typeof TimingCallTransformer;
+    };
+}
+//# sourceMappingURL=TimingDefaultTransformer.d.ts.map

package/dist/connectors/TimingDefaultTransformer.js

@@ -0,0 +1,16 @@
+import { DispatchingTransformer } from '@chronicle.app/etl';
+import TimingAppTransformer from './TimingAppTransformer.js';
+import TimingCallTransformer from './TimingCallTransformer.js';
+/**
+ * Routes the merged default stream to the focused transformers by record type:
+ * app usage and time entries → `TimingAppTransformer` (source `timing-app`),
+ * calls → `TimingCallTransformer` (re-sourced to `apple-call-history` so they fold with
+ * the Apple Call History plugin).
+ */
+export default class TimingDefaultTransformer extends DispatchingTransformer {
+    static routes = {
+        'app-activities': TimingAppTransformer,
+        'time-entries': TimingAppTransformer,
+        calls: TimingCallTransformer,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { TimingDefaultExtractor } from './connectors/TimingDefaultExtractor.js';
+export { default as TimingDefaultTransformer } from './connectors/TimingDefaultTransformer.js';
+export { AppUsageExtractor } from './connectors/AppUsageExtractor.js';
+export { TimeEntriesExtractor } from './connectors/TimeEntriesExtractor.js';
+export { default as TimingAppTransformer } from './connectors/TimingAppTransformer.js';
+export { TimingCallExtractor } from './connectors/TimingCallExtractor.js';
+export { default as TimingCallTransformer } from './connectors/TimingCallTransformer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,10 @@
+// Export extractors + transformers for plugin scanning.
+// `default` (the reverse-chronological merge) is the default type; the focused
+// extractors are opt-in via `-t app-usage|time-entries|calls`.
+export { TimingDefaultExtractor } from './connectors/TimingDefaultExtractor.js';
+export { default as TimingDefaultTransformer } from './connectors/TimingDefaultTransformer.js';
+export { AppUsageExtractor } from './connectors/AppUsageExtractor.js';
+export { TimeEntriesExtractor } from './connectors/TimeEntriesExtractor.js';
+export { default as TimingAppTransformer } from './connectors/TimingAppTransformer.js';
+export { TimingCallExtractor } from './connectors/TimingCallExtractor.js';
+export { default as TimingCallTransformer } from './connectors/TimingCallTransformer.js';

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@chronicle.app/timing-app",
+  "version": "0.3.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.lib.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint src --ext .ts,.js",
+    "test": "node --test src/*.test.js"
+  },
+  "keywords": [
+    "chronicle",
+    "timing",
+    "app-usage",
+    "time-tracking"
+  ],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Chronicle plugin for extracting app usage, projects, and time blocks from Timing.app",
+  "devDependencies": {
+    "@chronicle.app/etl": "0.3.0",
+    "@chronicle.app/schema": "0.3.0",
+    "@chronicle.app/tsconfig": "0.3.0",
+    "@types/node": "^22.10.1",
+    "typescript": "^5.7.2"
+  },
+  "homepage": "https://chronicle.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chronicle-app/chronicle.git",
+    "directory": "plugins/timing-app"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@chronicle.app/etl-sqlite": "0.3.0",
+    "@chronicle.app/icloud": "0.3.0",
+    "zod": "^3.24.1"
+  },
+  "peerDependencies": {
+    "@chronicle.app/etl": ">=0.1.0 <1.0.0",
+    "@chronicle.app/schema": ">=0.1.0 <1.0.0"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "chronicle": {
+    "plugin": true,
+    "sources": {
+      "timing-app": {
+        "strategies": {
+          "app-db": {
+            "delivery": "local",
+            "recordTypes": [
+              "app-activities",
+              "time-entries",
+              "calls"
+            ],
+            "default": true
+          }
+        },
+        "platforms": [
+          "darwin"
+        ]
+      }
+    }
+  }
+}