@chronicle.app/timing-app 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Louis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @chronicle.app/timing-app
+
+Chronicle plugin that extracts app/screen usage, manually-logged time entries,
+and relayed phone/FaceTime call history from
+[Timing.app](https://timingapp.com)'s local SQLite database.
+
+## Source
+
+`~/Library/Application Support/info.eurocomp.Timing2/SQLite.db` (opened read-only).
+Timestamps are Unix epoch seconds.
+
+Timing is partly a relay: Mac `AppActivity`/`TaskActivity`/`Project` are native,
+while iOS app usage rides in `AppActivity` via Apple Screen Time, and Apple Call
+History rides in `Event`.
+
+## Extraction types
+
+Bare `chronicle extract timing-app` runs the default extractor — a
+reverse-chronological merge of the three focused streams below (so `--limit 1`
+is the single most-recent record across all of them). Each stream is also
+selectable on its own:
+
+| `--type`         | Table                          | Emits                             |
+| ---------------- | ------------------------------ | --------------------------------- |
+| (none, default)  | all three, merged newest-first | —                                 |
+| `app-activities` | `AppActivity`                  | `ExecuteAction` + `DeviceSession` |
+| `time-entries`   | `TaskActivity`                 | `ExperienceAction` + `Session`    |
+| `calls`          | `Event` (call relay)           | `CallAction` + `CallSession`      |
+
+## Mapping
+
+- **App usage → `ExecuteAction` + `DeviceSession`.** The action carries the
+  measured span (`startTime`/`endTime`), `agent: @me`, `object`: the
+  `SoftwareApplication`, `instrument`: the `Device`, `result`: the `DeviceSession`.
+  The session carries `isPartOf` → Project and, for the on-screen resource, a
+  URL-keyed web `Entity` or a realm-scoped filesystem entry as its `subject`.
+  A filesystem entry is keyed by path within the machine's name-keyed `:Realm`
+  (`source: hostname`, via `inRealm`) — not globally, since a path isn't unique.
+  A trailing-slash path is a `:Directory` and lands on `workingDirectory` (the
+  terminal CWD / Finder folder the block happened in); any other path IS the
+  media object living there, typed by extension as far as a path-only source can
+  tell (`ImageObject`/`AudioObject`/`VideoObject`/`DocumentObject`, else a plain
+  `MediaObject` a byte-reader may refine later). The window title, when it adds
+  anything beyond the subject's name, holds the session's `name`.
+- **Time entry → `ExperienceAction` + `Session`.** A manually-logged block of
+  real time (Timing's "time entries"; each belongs to a project). The action
+  carries the real occurrence (`startTime`/`endTime`, not `scheduledTime`); the
+  lean `Session` object carries `isPartOf` → Project, `name` (title), and `description` (notes).
+- **Project ancestry** is nested via `isPartOf` on the session (leaf → parent →
+  …), not emitted as standalone records.
+- **Call relay (`--type calls`).** Timing relays Apple Call History; this plugin
+  reads that DB. It emits `CallAction`/`CallSession` under `source: apple-call-history`
+  - the shared call UUID, so it folds with the Apple Call History plugin's richer
+    Apple records — supplying the long tail Apple prunes. Direction is lost and
+    named contacts carry no number, so these are thin (a name, no participant).
+
+## Identity
+
+- App: bundle id (`source: apple-bundle-id`) where present, else `timing-app` +
+  executable/title. Never keyed on the local `Application.id`.
+- Device: `timing-app` + `Device.globalID`, with the hardware MAC linked via
+  `sameAs` (`source: mac-address`) on Macs.
+- `@me`: Timing has no account of its own, so the self node is just the `@me` tag
+  sourced to `timing-app` (no assumed name); the token merges it with the
+  subject's named identities from other sources.
+
+## Usage
+
+```bash
+# Default merge, recent window (~90 days), newest-first
+chronicle extract timing-app
+
+# Full history
+chronicle extract timing-app --all --limit 0
+
+# A single focused stream
+chronicle extract timing-app --type app-activities
+chronicle extract timing-app --type time-entries
+chronicle extract timing-app --type calls
+
+# Another copy of the database
+chronicle extract timing-app --input /path/to/SQLite.db
+```
+
+Tests use a synthetic Timing `SQLite.db` and a synthetic AddressBook under a
+temporary `HOME`, so they never read the host's Timing data or contacts.

package/dist/connectors/AppUsageExtractor.d.ts

@@ -0,0 +1,20 @@
+import { Record } from '@chronicle.app/etl';
+import TimingAppTransformer from './TimingAppTransformer.js';
+import { TimingDbExtractor } from './TimingDbExtractor.js';
+/**
+ * Automatic app/screen usage from Timing's `AppActivity` table (6M+ rows),
+ * streamed newest-first with a cursor. Each row → an `ExecuteAction` with a
+ * `DeviceSession` result.
+ */
+export declare class AppUsageExtractor extends TimingDbExtractor<typeof AppUsageExtractor> {
+    static source: string;
+    static description: string;
+    static recordTypes: string[];
+    static default: boolean;
+    static defaultTransformer: typeof TimingAppTransformer;
+    extract(): AsyncGenerator<Record>;
+    private rows;
+    private buildRecord;
+    determineCount(): Promise<number | null>;
+}
+//# sourceMappingURL=AppUsageExtractor.d.ts.map

package/dist/connectors/AppUsageExtractor.js

@@ -0,0 +1,86 @@
+import { iterateRows } from '@chronicle.app/etl-sqlite';
+import TimingAppTransformer from './TimingAppTransformer.js';
+import { TimingDbExtractor } from './TimingDbExtractor.js';
+/**
+ * Automatic app/screen usage from Timing's `AppActivity` table (6M+ rows),
+ * streamed newest-first with a cursor. Each row → an `ExecuteAction` with a
+ * `DeviceSession` result.
+ */
+export class AppUsageExtractor extends TimingDbExtractor {
+    static source = 'timing-app';
+    static description = 'Automatic app and screen usage';
+    static recordTypes = ['app-activities'];
+    static default = false;
+    static defaultTransformer = TimingAppTransformer;
+    async *extract() {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        const projectChain = this.projectChainResolver();
+        const devices = this.loadDevices();
+        for (const row of this.rows()) {
+            yield this.buildRecord(row, devices, projectChain);
+        }
+    }
+    rows() {
+        const since = this.sinceSeconds();
+        const until = this.untilSeconds();
+        const conditions = ['a.isDeleted = 0'];
+        const params = [];
+        if (since !== null) {
+            conditions.push('a.startDate > ?');
+            params.push(since);
+        }
+        if (until !== null) {
+            conditions.push('a.startDate < ?');
+            params.push(until);
+        }
+        const limit = this.getEffectiveLimit();
+        let sql = `
+      SELECT CAST(a.id AS TEXT) AS id, a.startDate, a.endDate,
+             CAST(a.localDeviceID AS TEXT) AS deviceLocalId,
+             app.bundleIdentifier AS bundleIdentifier, app.executable AS executable,
+             app.title AS appTitle,
+             CAST(a.projectID AS TEXT) AS projectId,
+             t.stringValue AS windowTitle, p.stringValue AS pathString
+      FROM AppActivity a
+      LEFT JOIN Application app ON a.applicationID = app.id
+      LEFT JOIN Title t ON a.titleID = t.id
+      LEFT JOIN Path p ON a.pathID = p.id
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY a.startDate DESC`;
+        if (limit !== null) {
+            sql += ` LIMIT ?`;
+            params.push(limit);
+        }
+        return iterateRows(this.db.prepare(sql), ...params);
+    }
+    buildRecord(row, devices, projectChain) {
+        return this.createRecord({}, {
+            recordType: 'app-activities',
+            id: row.id,
+            startDate: row.startDate,
+            endDate: row.endDate,
+            app: {
+                bundleIdentifier: row.bundleIdentifier || null,
+                executable: row.executable || null,
+                title: row.appTitle || null,
+            },
+            device: devices.get(row.deviceLocalId) ?? null,
+            projectChain: projectChain(row.projectId),
+            windowTitle: row.windowTitle || null,
+            pathString: row.pathString || null,
+        });
+    }
+    async determineCount() {
+        if (!this.db)
+            return null;
+        try {
+            const total = this.countWindow('AppActivity', 'startDate');
+            const limit = this.getEffectiveLimit();
+            return limit === null ? total : Math.min(limit, total);
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/connectors/TimeEntriesExtractor.d.ts

@@ -0,0 +1,21 @@
+import { Record } from '@chronicle.app/etl';
+import TimingAppTransformer from './TimingAppTransformer.js';
+import { TimingDbExtractor } from './TimingDbExtractor.js';
+/**
+ * Manually-logged time entries from Timing's `TaskActivity` table. Timing calls
+ * these "time entries" (each belongs to a project). Small and high-signal —
+ * deliberately recorded, unlike the automatic app usage. Each → an
+ * `ExperienceAction` carrying a lean `Session`.
+ */
+export declare class TimeEntriesExtractor extends TimingDbExtractor<typeof TimeEntriesExtractor> {
+    static source: string;
+    static description: string;
+    static recordTypes: string[];
+    static default: boolean;
+    static defaultTransformer: typeof TimingAppTransformer;
+    extract(): AsyncGenerator<Record>;
+    private rows;
+    private buildRecord;
+    determineCount(): Promise<number | null>;
+}
+//# sourceMappingURL=TimeEntriesExtractor.d.ts.map

package/dist/connectors/TimeEntriesExtractor.js

@@ -0,0 +1,73 @@
+import { iterateRows } from '@chronicle.app/etl-sqlite';
+import TimingAppTransformer from './TimingAppTransformer.js';
+import { TimingDbExtractor } from './TimingDbExtractor.js';
+/**
+ * Manually-logged time entries from Timing's `TaskActivity` table. Timing calls
+ * these "time entries" (each belongs to a project). Small and high-signal —
+ * deliberately recorded, unlike the automatic app usage. Each → an
+ * `ExperienceAction` carrying a lean `Session`.
+ */
+export class TimeEntriesExtractor extends TimingDbExtractor {
+    static source = 'timing-app';
+    static description = 'Manually logged time entries';
+    static recordTypes = ['time-entries'];
+    static default = false;
+    static defaultTransformer = TimingAppTransformer;
+    async *extract() {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        const projectChain = this.projectChainResolver();
+        for (const row of this.rows()) {
+            yield this.buildRecord(row, projectChain);
+        }
+    }
+    rows() {
+        const since = this.sinceSeconds();
+        const until = this.untilSeconds();
+        const conditions = ['isDeleted = 0', 'isRunning = 0'];
+        const params = [];
+        if (since !== null) {
+            conditions.push('startDate > ?');
+            params.push(since);
+        }
+        if (until !== null) {
+            conditions.push('startDate < ?');
+            params.push(until);
+        }
+        const limit = this.getEffectiveLimit();
+        let sql = `
+      SELECT CAST(id AS TEXT) AS id, startDate, endDate,
+             CAST(projectID AS TEXT) AS projectId, title, notes
+      FROM TaskActivity
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY startDate DESC`;
+        if (limit !== null) {
+            sql += ` LIMIT ?`;
+            params.push(limit);
+        }
+        return iterateRows(this.db.prepare(sql), ...params);
+    }
+    buildRecord(row, projectChain) {
+        return this.createRecord({}, {
+            recordType: 'time-entries',
+            id: row.id,
+            startDate: row.startDate,
+            endDate: row.endDate,
+            title: row.title || null,
+            notes: row.notes || null,
+            projectChain: projectChain(row.projectId),
+        });
+    }
+    async determineCount() {
+        if (!this.db)
+            return null;
+        try {
+            const total = this.countWindow('TaskActivity', 'startDate', ' AND isRunning = 0');
+            const limit = this.getEffectiveLimit();
+            return limit === null ? total : Math.min(limit, total);
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/connectors/TimingAppTransformer.d.ts

@@ -0,0 +1,48 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { ActionAndChildren } from '@chronicle.app/schema';
+export default class TimingAppTransformer extends ChronicleTransformer {
+    static source: string;
+    private meAgent?;
+    transform(record: Record): Promise<ActionAndChildren[]>;
+    /**
+     * The account owner, tagged `@me`. Timing has no account of its own (and it is
+     * not an iCloud identity), so we don't assume a name — the node is just the
+     * `@me` tag sourced to Timing, keyed on `['@type','source']`. The `@me` token
+     * merges it with the subject's named identities from other sources.
+     */
+    private me;
+    /**
+     * A Project node with its ancestry nested via isPartOf. `chain` is leaf-first
+     * ([self, parent, ...]); returns the leaf node, or null when unattributed.
+     *
+     * Each node asserts `isPartOf` as the complete parent set as of this read, so
+     * a project reparented (or promoted to root) in Timing closes its old parent
+     * edge instead of accumulating both.
+     */
+    private buildProjectChain;
+    private buildAppActivity;
+    /** The on-screen resource: a URL-keyed web page, or a realm-scoped filesystem entry. */
+    private buildResource;
+    /**
+     * The logical machine as a name-keyed `:Realm` — a file's `inRealm` scope and
+     * the device's `inRealm`. Keyed on the normalized name (Timing's device name →
+     * `pat-mbp`), so it folds with the same machine seen by the shell plugin, unifies
+     * across sources, and survives the hardware migrating.
+     */
+    private buildRealm;
+    /**
+     * The physical device — the action's `instrument`. Keyed on Timing's stable
+     * device id (with the hardware MAC linked via `sameAs`), so distinct hardware
+     * stays distinct: two MAC addresses are two devices, never merged. `inRealm`
+     * links it to the logical machine (`realm`) it runs on.
+     */
+    private buildDevice;
+    private buildApplication;
+    /**
+     * A manually-logged time entry. It's real lived activity (not a plan), so it's
+     * an `ExperienceAction` carrying the real occurrence, with the produced `Session`
+     * as its `result` — symmetric with app usage (`ExecuteAction` → `DeviceSession`).
+     */
+    private buildTimeEntry;
+}
+//# sourceMappingURL=TimingAppTransformer.d.ts.map