@chronicle.app/apple-call-history 0.3.0 → 0.5.0

package/README.md

@@ -9,7 +9,8 @@ and folds them into the existing comms identity graph (iMessage/WhatsApp via
 `~/Library/Application Support/CallHistoryDB/CallHistory.storedata` (read-only) —
 the rich, per-record source (direction, number, duration, participants).
 
-Calls emit `source: apple-call-history`, `sourceId = <call UUID>` (`ZUNIQUE_ID`). Apple's
+A call's `CallSession` is keyed by `source: apple-call-history` and `sourceId = <call UUID>`
+(`ZUNIQUE_ID`), and its `CallAction` by that session (`result.sourceId`). Apple's
 store has a rolling retention (~recent calls); the **longer history that Apple
 prunes is relayed through Timing.app and lives in the `timing-app` plugin**
 (`-t calls`), which emits the same `apple-call-history` + UUID identity so the two

package/dist/connectors/AppleCallHistoryExtractor.d.ts

@@ -1,4 +1,4 @@
-import { Record } from '@chronicle.app/etl';
+import { Record, type DatabaseSchema, type Survey, type SurveyOptions } from '@chronicle.app/etl';
 import { SqliteExtractor } from '@chronicle.app/etl-sqlite';
 import CallHistoryTransformer from './CallHistoryTransformer.js';
 /**
@@ -15,10 +15,14 @@ export declare class AppleCallHistoryExtractor extends SqliteExtractor<typeof Ap
     static default: boolean;
     static defaultTransformer: typeof CallHistoryTransformer;
     static temporality: "event";
+    static databases: DatabaseSchema[];
     static schema: any;
-    /** call Z_PK → remote handle values (phone/email). */
+    private callFilter;
+    /** call Z_PK → remote handle values (phone/email), when the store has the table of them. */
     private loadParticipants;
     extract(): AsyncGenerator<Record>;
     determineCount(): Promise<number | null>;
+    /** The calls a run reads and when, with how long they lasted, to the second. */
+    survey(options?: SurveyOptions): Promise<Survey | null>;
 }
 //# sourceMappingURL=AppleCallHistoryExtractor.d.ts.map

package/dist/connectors/AppleCallHistoryExtractor.js

@@ -1,7 +1,25 @@
-import { SqliteExtractor, safariToUnixTimestamp, timeRangeConditions, unixToSafariTimestamp, iterateRows, } from '@chronicle.app/etl-sqlite';
+import { APPLE_EPOCH_OFFSET_SECONDS, SqliteExtractor, countsByMonth, monthSql, safariToUnixTimestamp, timeRangeConditions, unixToSafariTimestamp, iterateRows, } from '@chronicle.app/etl-sqlite';
 import { z } from 'zod';
 import CallHistoryTransformer from './CallHistoryTransformer.js';
 const DEFAULT_DB = `${process.env.HOME}/Library/Application Support/CallHistoryDB/CallHistory.storedata`;
+/** The columns of ZCALLRECORD that extract() and survey() read. */
+const CALL_COLUMNS = [
+    'Z_PK',
+    'ZUNIQUE_ID',
+    'ZDATE',
+    'ZDURATION',
+    'ZORIGINATED',
+    'ZADDRESS',
+    'ZNAME',
+    'ZPARTICIPANTGROUPUUID',
+];
+/** The columns a call's other participants are read from, as `table.column`. */
+const PARTICIPANT_COLUMNS = [
+    'Z_2REMOTEPARTICIPANTHANDLES.Z_2REMOTEPARTICIPANTCALLS',
+    'Z_2REMOTEPARTICIPANTHANDLES.Z_4REMOTEPARTICIPANTHANDLES',
+    'ZHANDLE.Z_PK',
+    'ZHANDLE.ZVALUE',
+];
 /**
  * Apple Call History — the primary, per-record-rich call source. Each record has
  * an explicit direction, address, name, duration, and (for groups) a participant
@@ -19,15 +37,40 @@ export class AppleCallHistoryExtractor extends SqliteExtractor {
     static default = true;
     static defaultTransformer = CallHistoryTransformer;
     static temporality = 'event';
+    // What extract() and survey() read, which a CallHistory.storedata must have.
+    // Core Data names the join table of a call's other participants, and its
+    // columns, by entity number, which a release can change. A store without
+    // the table, in the second schema, or without its columns has its calls
+    // extracted without who else was on a group call.
+    static databases = [
+        {
+            tables: {
+                ZCALLRECORD: CALL_COLUMNS,
+                Z_2REMOTEPARTICIPANTHANDLES: ['Z_2REMOTEPARTICIPANTCALLS', 'Z_4REMOTEPARTICIPANTHANDLES?'],
+                ZHANDLE: ['Z_PK', 'ZVALUE'],
+            },
+        },
+        { tables: { ZCALLRECORD: CALL_COLUMNS } },
+    ];
     static schema = SqliteExtractor.schema.omit({ input: true }).extend({
         input: z.string().describe('Path to CallHistory.storedata').default(DEFAULT_DB),
     });
-    /** call Z_PK → remote handle values (phone/email). */
+    // Calls with an id, within since/until. ZDATE is seconds since the Apple epoch.
+    callFilter() {
+        const range = timeRangeConditions('ZDATE', this.config, {
+            convert: date => unixToSafariTimestamp(date.getTime() / 1000),
+        });
+        const conditions = ['ZUNIQUE_ID IS NOT NULL', ...range.conditions];
+        return { where: conditions.join(' AND '), values: range.values };
+    }
+    /** call Z_PK → remote handle values (phone/email), when the store has the table of them. */
     loadParticipants() {
+        const map = new Map();
+        if (!PARTICIPANT_COLUMNS.every(column => this.has(column)))
+            return map;
         const rows = this.db.prepare(`SELECT j.Z_2REMOTEPARTICIPANTCALLS AS callPk, h.ZVALUE AS value
        FROM Z_2REMOTEPARTICIPANTHANDLES j
        JOIN ZHANDLE h ON h.Z_PK = j.Z_4REMOTEPARTICIPANTHANDLES`).all();
-        const map = new Map();
         for (const row of rows) {
             if (!row.value)
                 continue;
@@ -41,20 +84,14 @@ export class AppleCallHistoryExtractor extends SqliteExtractor {
         if (!this.db)
             throw new Error('Database not initialized');
         const participants = this.loadParticipants();
-        const conditions = ['ZUNIQUE_ID IS NOT NULL'];
-        const params = [];
-        const range = timeRangeConditions('ZDATE', this.config, {
-            convert: date => unixToSafariTimestamp(date.getTime() / 1000),
-        });
-        conditions.push(...range.conditions);
-        params.push(...range.values);
+        const { where, values: params } = this.callFilter();
         const limit = this.getEffectiveLimit();
         let sql = `
       SELECT Z_PK AS pk, ZUNIQUE_ID AS uuid, ZDATE AS zdate, ZDURATION AS duration,
              ZORIGINATED AS originated, ZADDRESS AS address, ZNAME AS name,
              hex(ZPARTICIPANTGROUPUUID) AS groupUuid
       FROM ZCALLRECORD
-      WHERE ${conditions.join(' AND ')}
+      WHERE ${where}
       ORDER BY ZDATE DESC`;
         if (limit !== null) {
             sql += ` LIMIT ?`;
@@ -81,15 +118,42 @@ export class AppleCallHistoryExtractor extends SqliteExtractor {
         if (!this.db)
             return null;
         try {
+            // The calls a run reads: those with an id, within since and until.
+            const { where, values } = this.callFilter();
             const row = this.db
-                .prepare(`SELECT COUNT(*) AS n FROM ZCALLRECORD WHERE ZUNIQUE_ID IS NOT NULL`)
-                .get();
-            return row.n;
+                .prepare(`SELECT COUNT(*) AS n FROM ZCALLRECORD WHERE ${where}`)
+                .get(...values);
+            const limit = this.getEffectiveLimit();
+            return limit === null ? row.n : Math.min(row.n, limit);
         }
         catch {
             return null;
         }
     }
+    /** The calls a run reads and when, with how long they lasted, to the second. */
+    async survey(options = {}) {
+        if (!this.db)
+            return null;
+        const { where, values } = this.callFilter();
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS n, MIN(ZDATE) AS first, MAX(ZDATE) AS last,
+          COALESCE(ROUND(SUM(ZDURATION)), 0) AS seconds FROM ZCALLRECORD WHERE ${where}`)
+            .get(...values);
+        const byMonth = options.byMonth &&
+            countsByMonth(this.db
+                .prepare(`SELECT ${monthSql(`ZDATE + ${APPLE_EPOCH_OFFSET_SECONDS}`)} AS month, COUNT(*) AS n
+            FROM ZCALLRECORD WHERE ${where} GROUP BY month`)
+                .all(...values));
+        return {
+            calls: {
+                count: row.n,
+                ...(row.first !== null && { earliest: new Date(safariToUnixTimestamp(row.first) * 1000) }),
+                ...(row.last !== null && { latest: new Date(safariToUnixTimestamp(row.last) * 1000) }),
+                ...(byMonth && { byMonth }),
+                measures: [{ key: 'callSeconds', label: 'calls', value: row.seconds, unit: 'seconds' }],
+            },
+        };
+    }
 }
 function dedupe(values) {
     return [...new Set(values.map(v => v.trim()).filter(Boolean))];

package/dist/connectors/CallHistoryTransformer.js

@@ -1,5 +1,5 @@
 import { ChronicleTransformer, normalizePhoneNumber } from '@chronicle.app/etl';
-import { buildICloudPersonSchema, lookupContact } from '@chronicle.app/icloud';
+import { buildICloudPersonSchema, lookupContact } from '@chronicle.app/apple';
 // The call UUID is issued by Apple's phone/call subsystem and shared with Timing's
 // relay (see the timing-app plugin), so both key on it here and fold.
 const SOURCE = 'apple-call-history';
@@ -45,9 +45,9 @@ export default class CallHistoryTransformer extends ChronicleTransformer {
         };
         const action = {
             '@type': 'CallAction',
-            '@key': ['@type', 'source', 'sourceId'],
+            // Keyed by the session it made, which has the call's ID.
+            '@key': ['@type', 'source', 'result.sourceId'],
             source: SOURCE,
-            sourceId: ctx.uuid,
             startTime: secondsToISO(ctx.startSec),
             endTime: secondsToISO(ctx.startSec + ctx.durationSec),
             result: session,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronicle.app/apple-call-history",
-  "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 phone & FaceTime calls from Apple Call History (with a Timing.app supplement)",
   "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": {
@@ -68,7 +68,50 @@
             "recordTypes": [
               "calls"
             ],
-            "default": true
+            "default": true,
+            "locations": [
+              {
+                "path": "~/Library/Application Support/CallHistoryDB/CallHistory.storedata"
+              }
+            ],
+            "databases": [
+              {
+                "tables": {
+                  "ZCALLRECORD": [
+                    "Z_PK",
+                    "ZUNIQUE_ID",
+                    "ZDATE",
+                    "ZDURATION",
+                    "ZORIGINATED",
+                    "ZADDRESS",
+                    "ZNAME",
+                    "ZPARTICIPANTGROUPUUID"
+                  ],
+                  "Z_2REMOTEPARTICIPANTHANDLES": [
+                    "Z_2REMOTEPARTICIPANTCALLS",
+                    "Z_4REMOTEPARTICIPANTHANDLES?"
+                  ],
+                  "ZHANDLE": [
+                    "Z_PK",
+                    "ZVALUE"
+                  ]
+                }
+              },
+              {
+                "tables": {
+                  "ZCALLRECORD": [
+                    "Z_PK",
+                    "ZUNIQUE_ID",
+                    "ZDATE",
+                    "ZDURATION",
+                    "ZORIGINATED",
+                    "ZADDRESS",
+                    "ZNAME",
+                    "ZPARTICIPANTGROUPUUID"
+                  ]
+                }
+              }
+            ]
           }
         },
         "platforms": [