@chronicle.app/timing-app 0.3.0 → 0.5.0

package/README.md

@@ -44,7 +44,7 @@ selectable on its own:
   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
+  carries the real occurrence (`startTime`/`endTime`, not `scheduledStart`/`scheduledEnd`); 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.

package/dist/connectors/AppUsageExtractor.d.ts

@@ -1,4 +1,4 @@
-import { Record } from '@chronicle.app/etl';
+import { Record, type Survey, type SurveyOptions } from '@chronicle.app/etl';
 import TimingAppTransformer from './TimingAppTransformer.js';
 import { TimingDbExtractor } from './TimingDbExtractor.js';
 /**
@@ -16,5 +16,10 @@ export declare class AppUsageExtractor extends TimingDbExtractor<typeof AppUsage
     private rows;
     private buildRecord;
     determineCount(): Promise<number | null>;
+    /**
+     * The activities an uncapped run reads, when, and the time they span. The
+     * run's joins are left out: each is to a primary key, so it keeps every row.
+     */
+    survey(options?: SurveyOptions): Promise<Survey | null>;
 }
 //# sourceMappingURL=AppUsageExtractor.d.ts.map

package/dist/connectors/AppUsageExtractor.js

@@ -1,6 +1,6 @@
-import { iterateRows } from '@chronicle.app/etl-sqlite';
+import { getRow, iterateRows } from '@chronicle.app/etl-sqlite';
 import TimingAppTransformer from './TimingAppTransformer.js';
-import { TimingDbExtractor } from './TimingDbExtractor.js';
+import { TimingDbExtractor, startsByMonth, timeSurvey, } 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
@@ -22,18 +22,7 @@ export class AppUsageExtractor extends TimingDbExtractor {
         }
     }
     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 { conditions, params } = this.windowFilter('a');
         const limit = this.getEffectiveLimit();
         let sql = `
       SELECT CAST(a.id AS TEXT) AS id, a.startDate, a.endDate,
@@ -83,4 +72,21 @@ export class AppUsageExtractor extends TimingDbExtractor {
             return null;
         }
     }
+    /**
+     * The activities an uncapped run reads, when, and the time they span. The
+     * run's joins are left out: each is to a primary key, so it keeps every row.
+     */
+    async survey(options = {}) {
+        if (!this.db)
+            return null;
+        const { conditions, params } = this.windowFilter('a', this.sinceSeconds(null));
+        const rows = `FROM AppActivity a WHERE ${conditions.join(' AND ')}`;
+        const row = getRow(this.db.prepare(`SELECT COUNT(*) AS n, MIN(a.startDate) AS first, MAX(a.startDate) AS last,
+          COALESCE(SUM(a.endDate - a.startDate), 0) AS seconds
+        ${rows}`), ...params);
+        const byMonth = options.byMonth
+            ? startsByMonth(this.db, 'a.startDate', rows, params)
+            : undefined;
+        return { 'app-activities': timeSurvey(row, 'activities', byMonth) };
+    }
 }

package/dist/connectors/TimeEntriesExtractor.d.ts

@@ -1,4 +1,4 @@
-import { Record } from '@chronicle.app/etl';
+import { Record, type Survey, type SurveyOptions } from '@chronicle.app/etl';
 import TimingAppTransformer from './TimingAppTransformer.js';
 import { TimingDbExtractor } from './TimingDbExtractor.js';
 /**
@@ -17,5 +17,9 @@ export declare class TimeEntriesExtractor extends TimingDbExtractor<typeof TimeE
     private rows;
     private buildRecord;
     determineCount(): Promise<number | null>;
+    /** The entries an uncapped run reads, when, and the time they span. */
+    survey(options?: SurveyOptions): Promise<Survey | null>;
+    /** Finished entries within the window. */
+    private entryFilter;
 }
 //# sourceMappingURL=TimeEntriesExtractor.d.ts.map

package/dist/connectors/TimeEntriesExtractor.js

@@ -1,6 +1,6 @@
-import { iterateRows } from '@chronicle.app/etl-sqlite';
+import { getRow, iterateRows } from '@chronicle.app/etl-sqlite';
 import TimingAppTransformer from './TimingAppTransformer.js';
-import { TimingDbExtractor } from './TimingDbExtractor.js';
+import { TimingDbExtractor, startsByMonth, timeSurvey, } 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 —
@@ -22,18 +22,7 @@ export class TimeEntriesExtractor extends TimingDbExtractor {
         }
     }
     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 { conditions, params } = this.entryFilter();
         const limit = this.getEffectiveLimit();
         let sql = `
       SELECT CAST(id AS TEXT) AS id, startDate, endDate,
@@ -70,4 +59,21 @@ export class TimeEntriesExtractor extends TimingDbExtractor {
             return null;
         }
     }
+    /** The entries an uncapped run reads, when, and the time they span. */
+    async survey(options = {}) {
+        if (!this.db)
+            return null;
+        const { conditions, params } = this.entryFilter(this.sinceSeconds(null));
+        const rows = `FROM TaskActivity WHERE ${conditions.join(' AND ')}`;
+        const row = getRow(this.db.prepare(`SELECT COUNT(*) AS n, MIN(startDate) AS first, MAX(startDate) AS last,
+          COALESCE(SUM(endDate - startDate), 0) AS seconds
+        ${rows}`), ...params);
+        const byMonth = options.byMonth ? startsByMonth(this.db, 'startDate', rows, params) : undefined;
+        return { 'time-entries': timeSurvey(row, 'entries', byMonth) };
+    }
+    /** Finished entries within the window. */
+    entryFilter(since = this.sinceSeconds()) {
+        const { conditions, params } = this.windowFilter('TaskActivity', since);
+        return { conditions: [...conditions, 'TaskActivity.isRunning = 0'], params };
+    }
 }

package/dist/connectors/TimingAppTransformer.js

@@ -96,9 +96,9 @@ export default class TimingAppTransformer extends ChronicleTransformer {
         }
         const action = {
             '@type': 'ExecuteAction',
-            '@key': ['@type', 'source', 'sourceId'],
+            // Keyed by the session it made, which has the activity's ID.
+            '@key': ['@type', 'source', 'result.sourceId'],
             source: SOURCE,
-            sourceId: ctx.id,
             startTime: secondsToISO(ctx.startDate),
             endTime: secondsToISO(ctx.endDate),
             agent: this.me(),
@@ -108,7 +108,7 @@ export default class TimingAppTransformer extends ChronicleTransformer {
         if (app)
             action.object = app;
         if (device)
-            action.instrument = device;
+            action.instrument = [device];
         return action;
     }
     /** The on-screen resource: a URL-keyed web page, or a realm-scoped filesystem entry. */
@@ -190,10 +190,7 @@ export default class TimingAppTransformer extends ChronicleTransformer {
             sourceId: device.globalId,
             name: device.name,
         };
-        // Kind is open-ended data on :category (not a subclass); make/model on :model.
-        const category = deviceCategory(device.model);
-        if (category)
-            node.category = [category];
+        // Its make and model, such as `Mac15,3`, says what kind of device it is.
         if (device.model)
             node.model = device.model;
         if (device.mac) {
@@ -254,9 +251,9 @@ export default class TimingAppTransformer extends ChronicleTransformer {
             session.isPartOf = [project];
         const action = {
             '@type': 'ExperienceAction',
-            '@key': ['@type', 'source', 'sourceId'],
+            // Keyed by the session it made, which has the time entry's ID.
+            '@key': ['@type', 'source', 'result.sourceId'],
             source: SOURCE,
-            sourceId: ctx.id,
             startTime: secondsToISO(ctx.startDate),
             endTime: secondsToISO(ctx.endDate),
             agent: this.me(),
@@ -268,18 +265,6 @@ export default class TimingAppTransformer extends ChronicleTransformer {
 function secondsToISO(seconds) {
     return new Date(seconds * 1000).toISOString();
 }
-/** The device kind (open-ended :category data), inferred from Timing's model code. */
-function deviceCategory(model) {
-    if (!model)
-        return null;
-    if (/^Mac/i.test(model))
-        return 'computer';
-    if (/^iPhone/i.test(model))
-        return 'phone';
-    if (/^iPad/i.test(model))
-        return 'tablet';
-    return null;
-}
 /** Normalize a Timing Path value to an absolute filesystem path, or null if it isn't one. */
 function toFilePath(value) {
     let p = value;

package/dist/connectors/TimingCallExtractor.d.ts

@@ -1,4 +1,4 @@
-import { Record } from '@chronicle.app/etl';
+import { Record, type Survey, type SurveyOptions } from '@chronicle.app/etl';
 import { SqliteExtractor } from '@chronicle.app/etl-sqlite';
 import TimingCallTransformer from './TimingCallTransformer.js';
 /**
@@ -21,5 +21,9 @@ export declare class TimingCallExtractor extends SqliteExtractor<typeof TimingCa
     static temporality: "event";
     static schema: any;
     extract(): AsyncGenerator<Record>;
+    /** The calls a run reads, when, and the time they span; a call with no end spans none. */
+    survey(options?: SurveyOptions): Promise<Survey | null>;
+    /** Call History events, not deleted, that start after since and before until. */
+    private callFilter;
 }
 //# sourceMappingURL=TimingCallExtractor.d.ts.map

package/dist/connectors/TimingCallExtractor.js

@@ -1,7 +1,8 @@
 import { normalizePhoneNumber } from '@chronicle.app/etl';
-import { SqliteExtractor, iterateRows } from '@chronicle.app/etl-sqlite';
+import { SqliteExtractor, getRow, iterateRows } from '@chronicle.app/etl-sqlite';
 import { z } from 'zod';
 import TimingCallTransformer from './TimingCallTransformer.js';
+import { startsByMonth, timeSurvey } from './TimingDbExtractor.js';
 const DEFAULT_DB = `${process.env.HOME}/Library/Application Support/info.eurocomp.Timing2/SQLite.db`;
 /**
  * Timing.app's relay of Apple Call History — the historical supplement for the
@@ -27,20 +28,7 @@ export class TimingCallExtractor extends SqliteExtractor {
     async *extract() {
         if (!this.db)
             throw new Error('Database not initialized');
-        const conditions = [
-            "i.type = 'com.apple.CallHistory'",
-            'e.deleted_at IS NULL',
-            'e.origin_id IS NOT NULL',
-        ];
-        const params = [];
-        if (this.config.since) {
-            conditions.push('e.start_date > ?');
-            params.push(this.config.since.getTime() / 1000);
-        }
-        if (this.config.until) {
-            conditions.push('e.start_date < ?');
-            params.push(this.config.until.getTime() / 1000);
-        }
+        const { conditions, params } = this.callFilter();
         const limit = this.getEffectiveLimit();
         let sql = `
       SELECT e.origin_id AS uuid, e.start_date AS startSec, e.end_date AS endSec,
@@ -75,4 +63,39 @@ export class TimingCallExtractor extends SqliteExtractor {
             });
         }
     }
+    /** The calls a run reads, when, and the time they span; a call with no end spans none. */
+    async survey(options = {}) {
+        if (!this.db)
+            return null;
+        const { conditions, params } = this.callFilter();
+        const rows = `FROM Event e
+        JOIN Integration i ON e.integration_id = i.id
+        LEFT JOIN EventSource es ON e.event_source_id = es.id
+        WHERE ${conditions.join(' AND ')}`;
+        const row = getRow(this.db.prepare(`SELECT COUNT(*) AS n, MIN(e.start_date) AS first, MAX(e.start_date) AS last,
+          COALESCE(SUM(e.end_date - e.start_date), 0) AS seconds
+        ${rows}`), ...params);
+        const byMonth = options.byMonth
+            ? startsByMonth(this.db, 'e.start_date', rows, params)
+            : undefined;
+        return { calls: timeSurvey(row, 'calls', byMonth) };
+    }
+    /** Call History events, not deleted, that start after since and before until. */
+    callFilter() {
+        const conditions = [
+            "i.type = 'com.apple.CallHistory'",
+            'e.deleted_at IS NULL',
+            'e.origin_id IS NOT NULL',
+        ];
+        const params = [];
+        if (this.config.since) {
+            conditions.push('e.start_date > ?');
+            params.push(this.config.since.getTime() / 1000);
+        }
+        if (this.config.until) {
+            conditions.push('e.start_date < ?');
+            params.push(this.config.until.getTime() / 1000);
+        }
+        return { conditions, params };
+    }
 }

package/dist/connectors/TimingCallTransformer.js

@@ -1,5 +1,5 @@
 import { ChronicleTransformer, normalizePhoneNumber } from '@chronicle.app/etl';
-import { lookupContact, lookupContactByName } from '@chronicle.app/icloud';
+import { lookupContact, lookupContactByName } from '@chronicle.app/apple';
 // The call UUID is Apple's (relayed through Timing's Event.origin_id), so calls
 // key on `apple-call-history` + UUID and fold with the Apple Call History plugin's calls.
 const SOURCE = 'apple-call-history';
@@ -61,9 +61,10 @@ export default class TimingCallTransformer extends ChronicleTransformer {
         }
         return {
             '@type': 'CallAction',
-            '@key': ['@type', 'source', 'sourceId'],
+            // Keyed by its session, as the apple-call-history plugin keys a call, so
+            // the two fold into one call.
+            '@key': ['@type', 'source', 'result.sourceId'],
             source: SOURCE,
-            sourceId: ctx.uuid,
             startTime: secondsToISO(ctx.startSec),
             endTime: secondsToISO(ctx.endSec ?? ctx.startSec),
             result: session,

package/dist/connectors/TimingDbExtractor.d.ts

@@ -1,4 +1,6 @@
+import type { KindSurvey } from '@chronicle.app/etl';
 import { SqliteExtractor } from '@chronicle.app/etl-sqlite';
+import type { DatabaseSync, SQLInputValue } from 'node:sqlite';
 export declare const DEFAULT_DB: string;
 export declare const DEFAULT_WINDOW_DAYS = 90;
 export interface TimingDevice {
@@ -27,14 +29,39 @@ export declare abstract class TimingDbExtractor<SelfClass extends typeof SqliteE
      * 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.
      */
-    protected sinceSeconds(): number | null;
+    protected sinceSeconds(limit?: number | null): number | null;
     protected untilSeconds(): number | null;
+    /** Rows of `alias` not deleted that start after `since` and before `until`. */
+    protected windowFilter(alias: string, since?: number | null): {
+        conditions: string[];
+        params: number[];
+    };
     protected loadDevices(): Map<string, TimingDevice>;
     protected loadProjects(): Map<string, any>;
     /** A resolver that nests a project's full ancestry (leaf-first) for a row. */
     protected projectChainResolver(): (id: string | null) => TimingProject[];
     protected countWindow(table: string, col: string, extra?: string): number;
 }
+/**
+ * One aggregate over a kind's rows: how many, their first and last start in
+ * epoch seconds, and the seconds they span.
+ */
+export interface SpanRow {
+    n: number;
+    first: number | null;
+    last: number | null;
+    seconds: number;
+}
+/** A kind's survey from its aggregate, with its months when asked. */
+export declare function timeSurvey(row: SpanRow, label: string, byMonth?: KindSurvey['byMonth']): KindSurvey;
+/**
+ * How many of a kind's rows start in each month, over the FROM and WHERE of
+ * its aggregate.
+ * @param start A trusted SQL expression for the start, in epoch seconds
+ */
+export declare function startsByMonth(db: DatabaseSync, start: string, rows: string, params: SQLInputValue[]): {
+    [month: string]: number;
+};
 /** A project's ancestry, leaf-first: [self, parent, grandparent, ...]. */
 export declare function resolveChain(projects: Map<string, any>, id: string | null): TimingProject[];
 //# sourceMappingURL=TimingDbExtractor.d.ts.map

package/dist/connectors/TimingDbExtractor.js

@@ -1,4 +1,4 @@
-import { SqliteExtractor } from '@chronicle.app/etl-sqlite';
+import { SqliteExtractor, allRows, countsByMonth, monthSql } 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;
@@ -23,16 +23,31 @@ export class TimingDbExtractor extends SqliteExtractor {
      * 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() {
+    sinceSeconds(limit = this.getEffectiveLimit()) {
         if (this.config.since)
             return this.config.since.getTime() / 1000;
-        if (this.config.all || this.getEffectiveLimit() === null)
+        if (this.config.all || limit === null)
             return null;
         return (Date.now() - DEFAULT_WINDOW_DAYS * 86_400_000) / 1000;
     }
     untilSeconds() {
         return this.config.until ? this.config.until.getTime() / 1000 : null;
     }
+    /** Rows of `alias` not deleted that start after `since` and before `until`. */
+    windowFilter(alias, since = this.sinceSeconds()) {
+        const until = this.untilSeconds();
+        const conditions = [`${alias}.isDeleted = 0`];
+        const params = [];
+        if (since !== null) {
+            conditions.push(`${alias}.startDate > ?`);
+            params.push(since);
+        }
+        if (until !== null) {
+            conditions.push(`${alias}.startDate < ?`);
+            params.push(until);
+        }
+        return { conditions, params };
+    }
     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
@@ -93,6 +108,24 @@ export class TimingDbExtractor extends SqliteExtractor {
         return this.db.prepare(`SELECT COUNT(*) AS n FROM ${table} WHERE ${where}`).get(...params).n;
     }
 }
+/** A kind's survey from its aggregate, with its months when asked. */
+export function timeSurvey(row, label, byMonth) {
+    return {
+        count: row.n,
+        ...(row.first !== null && { earliest: new Date(row.first * 1000) }),
+        ...(row.last !== null && { latest: new Date(row.last * 1000) }),
+        ...(byMonth && { byMonth }),
+        measures: [{ key: 'duration', label, value: row.seconds, unit: 'seconds' }],
+    };
+}
+/**
+ * How many of a kind's rows start in each month, over the FROM and WHERE of
+ * its aggregate.
+ * @param start A trusted SQL expression for the start, in epoch seconds
+ */
+export function startsByMonth(db, start, rows, params) {
+    return countsByMonth(allRows(db.prepare(`SELECT ${monthSql(start)} AS month, COUNT(*) AS n ${rows} GROUP BY month`), ...params));
+}
 /** A project's ancestry, leaf-first: [self, parent, grandparent, ...]. */
 export function resolveChain(projects, id) {
     const chain = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronicle.app/timing-app",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -24,9 +24,9 @@
   "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",
+    "@chronicle.app/etl": "0.5.0",
+    "@chronicle.app/schema": "0.5.0",
+    "@chronicle.app/tsconfig": "0.5.0",
     "@types/node": "^22.10.1",
     "typescript": "^5.7.2"
   },
@@ -41,8 +41,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@chronicle.app/etl-sqlite": "0.3.0",
-    "@chronicle.app/icloud": "0.3.0",
+    "@chronicle.app/etl-sqlite": "0.5.0",
+    "@chronicle.app/apple": "0.5.0",
     "zod": "^3.24.1"
   },
   "peerDependencies": {
@@ -70,7 +70,12 @@
               "time-entries",
               "calls"
             ],
-            "default": true
+            "default": true,
+            "locations": [
+              {
+                "path": "~/Library/Application Support/info.eurocomp.Timing2/SQLite.db"
+              }
+            ]
           }
         },
         "platforms": [