@chronicle.app/apple-call-history 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,50 @@
+# @chronicle.app/apple-call-history
+
+Chronicle plugin that extracts phone & FaceTime calls from **Apple Call History**
+and folds them into the existing comms identity graph (iMessage/WhatsApp via
+`phone`/`email` + `@me`).
+
+## Source
+
+`~/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
+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
+fold into one call.
+
+The service (phone / FaceTime / VoIP) is not modeled yet (it needs
+cross-source action identity, since the shared key is Apple's UUID).
+
+## Frame
+
+A call is shared co-presence, not a directed send, so participants live on
+`:with`, not `:recipient`:
+
+```
+CallAction   agent = initiator (when known)   object = CallSession   startTime/endTime
+  CallSession  with = [participants other than @me]
+```
+
+- **Direction** (`ZORIGINATED`): outgoing → `agent: @me`; incoming 1:1 →
+  `agent`: the caller; incoming group → `agent` omitted.
+- **Connected vs missed** is derived from the span (missed ⇒ `endTime == startTime`).
+- **Participants** are `Person` keyed on `phone` (E.164) or `email` — folding into
+  the iMessage/WhatsApp graph and `@me`.
+- Blocked/private numbers (empty address) carry no participant.
+
+## Usage
+
+```bash
+chronicle extract apple-call-history                          # Apple Call History (rich; type: calls)
+chronicle extract apple-call-history --input /path/to/CallHistory.storedata --since 2025-01-01
+```
+
+## Tests
+
+Tests build a synthetic `CallHistory.storedata` and a synthetic AddressBook with
+`node:sqlite`, and pass the transformer an explicit iCloud `account` and a
+`lookupContact` over that AddressBook, so they never read the host's call history,
+contacts, or iCloud account.

package/dist/connectors/AppleCallHistoryExtractor.d.ts

@@ -0,0 +1,24 @@
+import { Record } from '@chronicle.app/etl';
+import { SqliteExtractor } from '@chronicle.app/etl-sqlite';
+import CallHistoryTransformer from './CallHistoryTransformer.js';
+/**
+ * Apple Call History — the primary, per-record-rich call source. Each record has
+ * an explicit direction, address, name, duration, and (for groups) a participant
+ * join table. Records key on the call UUID so they fold with the Timing relay.
+ */
+export declare class AppleCallHistoryExtractor extends SqliteExtractor<typeof AppleCallHistoryExtractor> {
+    static source: string;
+    static description: string;
+    static delivery: "local";
+    static strategy: string;
+    static recordTypes: string[];
+    static default: boolean;
+    static defaultTransformer: typeof CallHistoryTransformer;
+    static temporality: "event";
+    static schema: any;
+    /** call Z_PK → remote handle values (phone/email). */
+    private loadParticipants;
+    extract(): AsyncGenerator<Record>;
+    determineCount(): Promise<number | null>;
+}
+//# sourceMappingURL=AppleCallHistoryExtractor.d.ts.map

package/dist/connectors/AppleCallHistoryExtractor.js

@@ -0,0 +1,96 @@
+import { SqliteExtractor, 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`;
+/**
+ * Apple Call History — the primary, per-record-rich call source. Each record has
+ * an explicit direction, address, name, duration, and (for groups) a participant
+ * join table. Records key on the call UUID so they fold with the Timing relay.
+ */
+export class AppleCallHistoryExtractor extends SqliteExtractor {
+    // Plugin, CLI name, and record namespace are all `apple-call-history`, after
+    // Apple's CallHistory store (`com.apple.CallHistory`), which holds phone and
+    // FaceTime calls alike. Timing's relayed calls use it too, so the two fold.
+    static source = 'apple-call-history';
+    static description = 'Phone and FaceTime calls';
+    static delivery = 'local';
+    static strategy = 'app-db';
+    static recordTypes = ['calls'];
+    static default = true;
+    static defaultTransformer = CallHistoryTransformer;
+    static temporality = 'event';
+    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). */
+    loadParticipants() {
+        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;
+            const list = map.get(row.callPk) ?? [];
+            list.push(row.value);
+            map.set(row.callPk, list);
+        }
+        return map;
+    }
+    async *extract() {
+        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 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 ')}
+      ORDER BY ZDATE DESC`;
+        if (limit !== null) {
+            sql += ` LIMIT ?`;
+            params.push(limit);
+        }
+        for (const row of iterateRows(this.db.prepare(sql), ...params)) {
+            const handles = dedupe([
+                ...(participants.get(row.pk) ?? []),
+                ...(row.address ? [row.address] : []),
+            ]);
+            yield this.createRecord({}, {
+                recordType: 'calls',
+                uuid: row.uuid,
+                startSec: safariToUnixTimestamp(row.zdate),
+                durationSec: row.duration ?? 0,
+                originated: row.originated, // 1 out, 0 in
+                name: row.name || null,
+                handles,
+                groupUuid: row.groupUuid || null, // hex of ZPARTICIPANTGROUPUUID
+            });
+        }
+    }
+    async determineCount() {
+        if (!this.db)
+            return null;
+        try {
+            const row = this.db
+                .prepare(`SELECT COUNT(*) AS n FROM ZCALLRECORD WHERE ZUNIQUE_ID IS NOT NULL`)
+                .get();
+            return row.n;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+function dedupe(values) {
+    return [...new Set(values.map(v => v.trim()).filter(Boolean))];
+}

package/dist/connectors/CallHistoryTransformer.d.ts

@@ -0,0 +1,19 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { ActionAndChildren } from '@chronicle.app/schema';
+/**
+ * Modeled like a message (produced artifact → `result`, receiver → `recipient`):
+ *
+ *   CallAction  agent: caller
+ *     result: CallSession  recipient: [receiver(s)]   isPartOf: [Channel] (groups)
+ *
+ * The service (phone/FaceTime) is deferred; the message frame (object → result)
+ * will be unified across all comms plugins in a follow-up.
+ */
+export default class CallHistoryTransformer extends ChronicleTransformer {
+    static source: string;
+    private mePromise?;
+    transform(record: Record): Promise<ActionAndChildren[]>;
+    private me;
+    private buildAppleCall;
+}
+//# sourceMappingURL=CallHistoryTransformer.d.ts.map

package/dist/connectors/CallHistoryTransformer.js

@@ -0,0 +1,164 @@
+import { ChronicleTransformer, normalizePhoneNumber } from '@chronicle.app/etl';
+import { buildICloudPersonSchema, lookupContact } from '@chronicle.app/icloud';
+// 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';
+/**
+ * Modeled like a message (produced artifact → `result`, receiver → `recipient`):
+ *
+ *   CallAction  agent: caller
+ *     result: CallSession  recipient: [receiver(s)]   isPartOf: [Channel] (groups)
+ *
+ * The service (phone/FaceTime) is deferred; the message frame (object → result)
+ * will be unified across all comms plugins in a follow-up.
+ */
+export default class CallHistoryTransformer extends ChronicleTransformer {
+    static source = SOURCE;
+    mePromise;
+    async transform(record) {
+        if (record.extraction.recordType === 'calls') {
+            return [await this.buildAppleCall(record)];
+        }
+        return [];
+    }
+    // Optional config: `account` (an iCloud account, or null for none) and
+    // `lookupContact` replace the host's iCloud account and Contacts lookups.
+    me() {
+        if (!this.mePromise)
+            this.mePromise = buildICloudPersonSchema(this.config.account);
+        return this.mePromise;
+    }
+    async buildAppleCall(record) {
+        const ctx = record.context;
+        const outgoing = ctx.originated === 1;
+        const me = await this.me();
+        // Apple's per-call ZNAME is only meaningful for a 1:1 counterpart.
+        const singleName = ctx.handles.length === 1 ? ctx.name : null;
+        const others = ctx.handles
+            .map((h, i) => buildCallParty(h, i === 0 ? singleName : null, this.config.lookupContact))
+            .filter((p) => p !== null);
+        const session = {
+            '@type': 'CallSession',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: SOURCE,
+            sourceId: ctx.uuid,
+        };
+        const action = {
+            '@type': 'CallAction',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: SOURCE,
+            sourceId: ctx.uuid,
+            startTime: secondsToISO(ctx.startSec),
+            endTime: secondsToISO(ctx.startSec + ctx.durationSec),
+            result: session,
+        };
+        if (ctx.groupUuid) {
+            // Group call → a Channel (the roster), mirroring group messages.
+            const channel = {
+                '@type': 'Channel',
+                '@key': ['@type', 'source', 'sourceId'],
+                source: SOURCE,
+                sourceId: ctx.groupUuid,
+            };
+            if (others.length > 0)
+                channel.member = others;
+            session.isPartOf = [channel];
+            if (outgoing)
+                action.agent = me; // I called the group
+            else
+                session.recipient = [me]; // group called me; initiator unknown
+        }
+        else if (others.length === 1) {
+            if (outgoing) {
+                action.agent = me;
+                session.recipient = [others[0]];
+            }
+            else {
+                action.agent = others[0]; // the caller
+                session.recipient = [me];
+            }
+        }
+        else if (others.length === 0) {
+            // Blocked/private number — no keyable participant (and a name is not a
+            // session label). Keep the call on the timeline.
+            if (outgoing)
+                action.agent = me;
+        }
+        else if (outgoing) {
+            // Multiple handles without a group id (unusual), outgoing.
+            action.agent = me;
+            session.recipient = others;
+        }
+        else {
+            // Multiple handles, incoming — initiator not identifiable.
+            session.recipient = [me];
+        }
+        return action;
+    }
+}
+/**
+ * A call party as an `apple-call-history` identity (Apple's call history, which
+ * covers FaceTime/VoIP that never touch the phone network), with `sameAs` edges to
+ * the underlying handle (`phone` or `email`, kept nameless — a number has no
+ * canonical name) and, when in Contacts, the `apple-contacts` entry (its stable
+ * ZEXTERNALUUID carries the name). The party's name is Apple's ZNAME, falling
+ * back to the contact's name.
+ *
+ * Identity keys on the stable identifier alone (`['source','handle']` /
+ * `['source','sourceId']`), not `@type`: a bare handle could be a person, a
+ * business, or a robocaller — `@type` is a union annotation (`Agent` here), never
+ * part of the key. A contact card, where the kind is known, refines it (Person /
+ * Organization).
+ */
+function buildCallParty(handle, znameFallback, lookup = lookupContact) {
+    const value = handle.trim();
+    if (!value)
+        return null;
+    const isEmail = value.includes('@');
+    const canonical = isEmail ? value.toLowerCase() : normalizePhoneNumber(value) || value;
+    const contact = lookup(canonical);
+    const party = {
+        '@type': 'Agent',
+        '@key': ['source', 'handle'],
+        source: 'apple-call-history',
+        handle: canonical,
+    };
+    const name = znameFallback ?? contact?.fullName;
+    if (name)
+        party.name = name;
+    const sameAs = [
+        {
+            '@type': 'Agent',
+            '@key': ['source', 'handle'],
+            source: isEmail ? 'email' : 'phone',
+            handle: canonical,
+        },
+    ];
+    if (contact?.id)
+        sameAs.push(contactNode(contact));
+    party.sameAs = sameAs;
+    return party;
+}
+/**
+ * The Address Book entry, keyed on its portable id. Typed from the card — a person
+ * (has a name) or an organization (org-only card) — the one place the kind is known.
+ */
+function contactNode(contact) {
+    return {
+        '@type': contactType(contact),
+        '@key': ['source', 'sourceId'],
+        source: 'apple-contacts',
+        sourceId: contact.id,
+        ...(contact.fullName ? { name: contact.fullName } : {}),
+    };
+}
+function contactType(contact) {
+    if (contact.firstName || contact.lastName)
+        return 'Person';
+    if (contact.organization)
+        return 'Organization';
+    return 'Agent';
+}
+function secondsToISO(seconds) {
+    return new Date(seconds * 1000).toISOString();
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { AppleCallHistoryExtractor } from './connectors/AppleCallHistoryExtractor.js';
+export { default as CallHistoryTransformer } from './connectors/CallHistoryTransformer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,3 @@
+// Export extractor + transformer for plugin scanning
+export { AppleCallHistoryExtractor } from './connectors/AppleCallHistoryExtractor.js';
+export { default as CallHistoryTransformer } from './connectors/CallHistoryTransformer.js';

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@chronicle.app/apple-call-history",
+  "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",
+    "apple-call-history",
+    "phone",
+    "facetime"
+  ],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "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",
+    "@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/apple-call-history"
+  },
+  "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": {
+      "apple-call-history": {
+        "strategies": {
+          "app-db": {
+            "delivery": "local",
+            "recordTypes": [
+              "calls"
+            ],
+            "default": true
+          }
+        },
+        "platforms": [
+          "darwin"
+        ],
+        "requires": [
+          "full-disk-access"
+        ]
+      }
+    }
+  }
+}