@chronicle.app/things-todo 0.3.0 → 0.5.0

package/dist/connectors/ThingsTodoExtractor.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 ThingsTodoTransformer from './ThingsTodoTransformer.js';
 export declare class ThingsTodoExtractor extends SqliteExtractor<typeof ThingsTodoExtractor> {
@@ -9,12 +9,34 @@ export declare class ThingsTodoExtractor extends SqliteExtractor<typeof ThingsTo
     static description: string;
     static recordTypes: string[];
     static default: boolean;
+    static databases: {
+        tables: {
+            TMTask: string[];
+            TMTaskTag: string[];
+            TMTag: string[];
+            TMArea: string[];
+            TMAreaTag: string[];
+        };
+    }[];
     static schema: any;
     static defaultTransformer: typeof ThingsTodoTransformer;
+    /**
+     * The default database lives in a folder macOS guards: say whether it's
+     * missing or refused before SQLite reports "unable to open database file".
+     */
+    setup(): Promise<void>;
     /** The owner's name from the local machine, used when `agentName` isn't set. */
     protected resolveAgentName(): string | undefined;
     private getStatusLabel;
     extract(): AsyncGenerator<Record>;
+    /**
+     * The tasks and projects a run reads, by when each was created, and how
+     * many of the tasks are completed. A run groups its tag joins back to one
+     * row per task, and `uuid` is the key, so counting tasks counts its rows.
+     */
+    survey(options?: SurveyOptions): Promise<Survey | null>;
+    /** Tasks, projects and headings last modified within since and until, inclusive. */
+    private taskFilter;
     private getEnrichedAreas;
     private getEnrichedProjects;
     private getTagHierarchies;

package/dist/connectors/ThingsTodoExtractor.js

@@ -1,4 +1,5 @@
-import { SqliteExtractor, timeRangeConditions } from '@chronicle.app/etl-sqlite';
+import { fileError, } from '@chronicle.app/etl';
+import { SqliteExtractor, allRows, countsByMonth, monthSql, timeRangeConditions, } from '@chronicle.app/etl-sqlite';
 import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { z } from 'zod';
@@ -12,11 +13,20 @@ import ThingsTodoTransformer from './ThingsTodoTransformer.js';
  * cannot be hardcoded. Glob the Group Containers directory for the
  * `ThingsData-*` folder and return the database inside it.
  */
+const containerDir = `${process.env.HOME}/Library/Group Containers/JLMPQHK86H.com.culturedcode.ThingsMac`;
 function resolveThingsDbPath() {
-    const containerDir = `${process.env.HOME}/Library/Group Containers/JLMPQHK86H.com.culturedcode.ThingsMac`;
     const dbSuffix = 'Things Database.thingsdatabase/main.sqlite';
+    // Listing the container needs Full Disk Access; without it, fall through to
+    // the conventional path and let setup() say what's wrong.
     if (existsSync(containerDir)) {
-        const thingsDataDirs = readdirSync(containerDir).filter(name => name.startsWith('ThingsData-'));
+        let entries = [];
+        try {
+            entries = readdirSync(containerDir);
+        }
+        catch {
+            // Reported by setup().
+        }
+        const thingsDataDirs = entries.filter(name => name.startsWith('ThingsData-'));
         for (const dir of thingsDataDirs) {
             const dbPath = join(containerDir, dir, dbSuffix);
             if (existsSync(dbPath)) {
@@ -28,6 +38,16 @@ function resolveThingsDbPath() {
     // when Things is not installed.
     return join(containerDir, 'ThingsData', dbSuffix);
 }
+/** A kind's count and the first and last creation of its records, when there are any. */
+function created(row) {
+    if (!row)
+        return { count: 0 };
+    return {
+        count: row.n,
+        ...(row.first !== null && { earliest: new Date(row.first * 1000) }),
+        ...(row.last !== null && { latest: new Date(row.last * 1000) }),
+    };
+}
 export class ThingsTodoExtractor extends SqliteExtractor {
     static source = 'things-todo';
     static delivery = 'local';
@@ -40,6 +60,34 @@ export class ThingsTodoExtractor extends SqliteExtractor {
     static description = 'Tasks and projects';
     static recordTypes = ['tasks', 'projects'];
     static default = true;
+    // What extract() and survey() read, which a Things main.sqlite must have.
+    // Those marked `?` come only through `task.*` and `tag.*`, and a run does
+    // without them.
+    static databases = [
+        {
+            tables: {
+                TMTask: [
+                    'uuid',
+                    'title',
+                    'type',
+                    'status',
+                    'creationDate',
+                    'startDate?',
+                    'stopDate',
+                    'userModificationDate',
+                    'project',
+                    'heading',
+                    'area',
+                    'notes?',
+                    'trashed?',
+                ],
+                TMTaskTag: ['tasks', 'tags'],
+                TMTag: ['uuid', 'title', 'parent', 'shortcut?', 'usedDate?'],
+                TMArea: ['uuid', 'title'],
+                TMAreaTag: ['areas', 'tags'],
+            },
+        },
+    ];
     static schema = SqliteExtractor.schema.omit({ input: true }).extend({
         input: z
             .string()
@@ -51,6 +99,22 @@ export class ThingsTodoExtractor extends SqliteExtractor {
             .describe("Name of the task owner. Defaults to the OS account's full name"),
     });
     static defaultTransformer = ThingsTodoTransformer;
+    /**
+     * The default database lives in a folder macOS guards: say whether it's
+     * missing or refused before SQLite reports "unable to open database file".
+     */
+    async setup() {
+        const { input } = this.config;
+        if (input.startsWith(containerDir)) {
+            try {
+                readdirSync(containerDir);
+            }
+            catch (error) {
+                throw fileError(error, containerDir, 'Things library');
+            }
+        }
+        await super.setup();
+    }
     /** The owner's name from the local machine, used when `agentName` isn't set. */
     resolveAgentName() {
         return localAccountName();
@@ -72,17 +136,12 @@ export class ThingsTodoExtractor extends SqliteExtractor {
             throw new Error('Database not initialized');
         }
         const limit = this.getEffectiveLimit();
-        const { conditions, values } = timeRangeConditions('task.userModificationDate', this.config, {
-            sinceOp: '>=',
-            untilOp: '<=',
-        });
+        const { conditions, values } = this.taskFilter();
         let sql = `SELECT task.*, group_concat(DISTINCT tag.uuid) AS tag_ids,
       group_concat(DISTINCT tag.title) AS tag_titles FROM TMTask task
       LEFT JOIN TMTaskTag tagging ON task.uuid = tagging.tasks
       LEFT JOIN TMTag tag ON tagging.tags = tag.uuid
-      WHERE task.type IN (0, 1, 2)`;
-        if (conditions.length > 0)
-            sql += ' AND ' + conditions.join(' AND ');
+      WHERE ${conditions.join(' AND ')}`;
         sql += ' GROUP BY task.uuid ORDER BY task.userModificationDate DESC, task.uuid';
         if (limit !== null) {
             sql += ' LIMIT ?';
@@ -169,6 +228,46 @@ export class ThingsTodoExtractor extends SqliteExtractor {
             });
         }
     }
+    /**
+     * The tasks and projects a run reads, by when each was created, and how
+     * many of the tasks are completed. A run groups its tag joins back to one
+     * row per task, and `uuid` is the key, so counting tasks counts its rows.
+     */
+    async survey(options = {}) {
+        if (!this.db)
+            return null;
+        const { conditions, values } = this.taskFilter();
+        const kind = `CASE WHEN task.type IN (1, 2) THEN 'projects' ELSE 'tasks' END`;
+        const from = `FROM TMTask task WHERE ${conditions.join(' AND ')}`;
+        const rows = allRows(this.db.prepare(`SELECT ${kind} AS kind,
+          COUNT(*) AS n, MIN(task.creationDate) AS first, MAX(task.creationDate) AS last,
+          COUNT(*) FILTER (WHERE task.status = 3) AS completed
+        ${from} GROUP BY kind`), ...values);
+        const months = options.byMonth &&
+            allRows(this.db.prepare(`SELECT ${kind} AS kind, ${monthSql('task.creationDate')} AS month, COUNT(*) AS n
+          ${from} GROUP BY kind, month`), ...values);
+        // A kind's survey, with its months when asked.
+        const ofKind = (name) => ({
+            ...created(rows.find(row => row.kind === name)),
+            ...(months && { byMonth: countsByMonth(months.filter(row => row.kind === name)) }),
+        });
+        const tasks = rows.find(row => row.kind === 'tasks');
+        return {
+            tasks: {
+                ...ofKind('tasks'),
+                measures: [{ key: 'completed', label: 'completed', value: tasks?.completed ?? 0 }],
+            },
+            projects: ofKind('projects'),
+        };
+    }
+    /** Tasks, projects and headings last modified within since and until, inclusive. */
+    taskFilter() {
+        const { conditions, values } = timeRangeConditions('task.userModificationDate', this.config, {
+            sinceOp: '>=',
+            untilOp: '<=',
+        });
+        return { conditions: ['task.type IN (0, 1, 2)', ...conditions], values };
+    }
     async getEnrichedAreas(areaIds) {
         const enrichedAreas = new Map();
         if (areaIds.length === 0)

package/dist/connectors/ThingsTodoTransformer.js

@@ -42,9 +42,9 @@ export default class ThingsTodoTransformer extends ChronicleTransformer {
             const updateAction = {
                 '@type': 'UpdateAction',
                 timestamp: new Date(record.data.userModificationDate * 1000),
-                '@key': ['@type', 'source', 'sourceId'],
+                // Keyed by the task: Things keeps only its latest edit.
+                '@key': ['@type', 'source', 'object.sourceId'],
                 source: 'things-todo',
-                sourceId: record.data.uuid,
                 agent: user,
                 object: task,
             };
@@ -80,12 +80,13 @@ export default class ThingsTodoTransformer extends ChronicleTransformer {
         return actions;
     }
     buildAction({ data, timestamp, type, agentObj, taskObj, }) {
+        // A task is planned, completed, cancelled, or deleted once, so the task
+        // identifies the action.
         return {
             '@type': type,
             timestamp: new Date(timestamp * 1000),
-            '@key': ['@type', 'source', 'sourceId'],
+            '@key': ['@type', 'source', 'object.sourceId'],
             source: 'things-todo',
-            sourceId: data.uuid,
             agent: agentObj,
             object: taskObj,
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronicle.app/things-todo",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -19,9 +19,9 @@
   "type": "module",
   "description": "Chronicle things-todo extraction plugin",
   "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"
   },
@@ -36,7 +36,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@chronicle.app/etl-sqlite": "0.3.0",
+    "@chronicle.app/etl-sqlite": "0.5.0",
     "zod": "^3.24.1"
   },
   "peerDependencies": {
@@ -63,11 +63,59 @@
               "tasks",
               "projects"
             ],
-            "default": true
+            "default": true,
+            "locations": [
+              {
+                "path": "~/Library/Group Containers/JLMPQHK86H.com.culturedcode.ThingsMac/ThingsData*/Things Database.thingsdatabase/main.sqlite"
+              }
+            ],
+            "databases": [
+              {
+                "tables": {
+                  "TMTask": [
+                    "uuid",
+                    "title",
+                    "type",
+                    "status",
+                    "creationDate",
+                    "startDate?",
+                    "stopDate",
+                    "userModificationDate",
+                    "project",
+                    "heading",
+                    "area",
+                    "notes?",
+                    "trashed?"
+                  ],
+                  "TMTaskTag": [
+                    "tasks",
+                    "tags"
+                  ],
+                  "TMTag": [
+                    "uuid",
+                    "title",
+                    "parent",
+                    "shortcut?",
+                    "usedDate?"
+                  ],
+                  "TMArea": [
+                    "uuid",
+                    "title"
+                  ],
+                  "TMAreaTag": [
+                    "areas",
+                    "tags"
+                  ]
+                }
+              }
+            ]
           }
         },
         "platforms": [
           "darwin"
+        ],
+        "requires": [
+          "full-disk-access"
         ]
       }
     }