@chronicle.app/safari 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,9 @@
+# @chronicle.app/safari
+
+Read Safari's `History.db` with `SafariExtractor`, then emit one `ViewAction` per page visit with `SafariTransformer`. `input` defaults to `~/Library/Safari/History.db`; reading it needs Full Disk Access. The connection is read-only via built-in `node:sqlite`.
+
+Records are visits, newest first, with redirect hops left out. `since`/`until` are exclusive visit-time bounds, and `limit: 0` means unlimited.
+
+Each `ViewAction` is keyed by its timestamp. The visited page is an `Entity` keyed by its URL and named after the page title, or the URL when there is none. The agent is the iCloud account owner from `@chronicle.app/icloud`, omitted when no account can be read. An explicit `account` object (or null) describes exported data without a host account lookup.
+
+Tests use a synthetic history database and never read the host's browsing history or iCloud account.

package/dist/connectors/SafariExtractor.d.ts

@@ -0,0 +1,21 @@
+import { Record } from '@chronicle.app/etl';
+import { SqliteExtractor } from '@chronicle.app/etl-sqlite';
+import SafariTransformer from './SafariTransformer.js';
+export declare class SafariExtractor extends SqliteExtractor<typeof SafariExtractor> {
+    static source: string;
+    static delivery: "local";
+    static strategy: string;
+    static description: string;
+    static default: boolean;
+    static recordTypes: string[];
+    static newestFirst: boolean;
+    static schema: any;
+    static defaultTransformer: typeof SafariTransformer;
+    /** history_visits.id — Safari's own visit id, AUTOINCREMENT so never reused. */
+    keyOf(record: Record): string | null;
+    private visitFilter;
+    extract(): AsyncGenerator<Record>;
+    private processRow;
+    determineCount(): Promise<number | null>;
+}
+//# sourceMappingURL=SafariExtractor.d.ts.map

package/dist/connectors/SafariExtractor.js

@@ -0,0 +1,110 @@
+import { APPLE_EPOCH_OFFSET_SECONDS, SqliteExtractor, timeRangeConditions, unixToSafariTimestamp, iterateRows, } from '@chronicle.app/etl-sqlite';
+import { getICloudAccount } from '@chronicle.app/icloud';
+import { z } from 'zod';
+import SafariTransformer from './SafariTransformer.js';
+// since/until bounds land on visit_time, which is seconds since the Apple epoch
+const safariBound = (date) => unixToSafariTimestamp(Math.floor(date.getTime() / 1000));
+export class SafariExtractor extends SqliteExtractor {
+    static source = 'safari';
+    static delivery = 'local';
+    static strategy = 'app-db';
+    static description = 'Browsing history';
+    static default = true;
+    static recordTypes = ['views'];
+    // extract() orders by history_visits.visit_time desc, which with keyOf opts
+    // this extractor into the frontier cursor (incremental catch-up import).
+    static newestFirst = true;
+    static schema = SqliteExtractor.schema.omit({ input: true }).extend({
+        input: z
+            .string()
+            .describe('Path to Safari History.db file')
+            .default(`${process.env.HOME}/Library/Safari/History.db`),
+        account: z
+            .object({
+            accountID: z.string(),
+            email: z.string(),
+            displayName: z.string(),
+            dsid: z.string().optional(),
+        })
+            .nullable()
+            .optional(),
+    });
+    static defaultTransformer = SafariTransformer;
+    /** history_visits.id — Safari's own visit id, AUTOINCREMENT so never reused. */
+    keyOf(record) {
+        const visitId = record.data.visit_id;
+        return visitId === null || visitId === undefined ? null : String(visitId);
+    }
+    // Visits that landed on a page (redirect hops excluded), within since/until.
+    visitFilter() {
+        const range = timeRangeConditions('history_visits.visit_time', this.config, {
+            convert: safariBound,
+        });
+        const conditions = ['history_visits.redirect_destination IS NULL', ...range.conditions];
+        return { where: conditions.join(' AND '), values: range.values };
+    }
+    async *extract() {
+        if (!this.db) {
+            throw new Error('Database not initialized');
+        }
+        // 0 is the "no limit" convention (null here); the CLI's --limit default is the safety net
+        const limit = this.getEffectiveLimit();
+        const { where, values } = this.visitFilter();
+        let sql = `
+      SELECT history_visits.id AS visit_id,
+             history_visits.history_item,
+             history_visits.visit_time,
+             history_visits.title,
+             history_items.url,
+             cast(history_visits.visit_time + ${APPLE_EPOCH_OFFSET_SECONDS} as integer) AS unix_timestamp,
+             datetime(history_visits.visit_time + ${APPLE_EPOCH_OFFSET_SECONDS}, 'unixepoch') AS visit_datetime,
+             history_visits.origin
+      FROM history_visits
+      LEFT JOIN history_items ON history_items.id = history_visits.history_item
+      WHERE ${where}
+      ORDER BY history_visits.visit_time DESC`;
+        if (limit !== null) {
+            sql += ` LIMIT ?`;
+            values.push(limit);
+        }
+        const account = this.config.account === undefined ? await getICloudAccount() : this.config.account;
+        for (const row of iterateRows(this.db.prepare(sql), ...values)) {
+            const processedRow = this.processRow(row);
+            yield this.createRecord(processedRow, {
+                source: 'safari',
+                account,
+            });
+        }
+    }
+    processRow(row) {
+        return {
+            visit_id: row.visit_id,
+            history_item: row.history_item,
+            visit_time: row.visit_time,
+            title: row.title || null,
+            url: row.url,
+            unix_timestamp: row.unix_timestamp,
+            visit_datetime: row.visit_datetime,
+            origin: row.origin,
+            // Origin is an integer in Safari's schema - we can't determine device type from it directly
+            device_type: 'desktop', // Default to desktop since we can't reliably detect mobile vs desktop
+        };
+    }
+    async determineCount() {
+        if (!this.db)
+            return null;
+        try {
+            // Same filters as the main query, counted
+            const { where, values } = this.visitFilter();
+            const row = this.db
+                .prepare(`SELECT COUNT(*) AS n FROM history_visits
+           LEFT JOIN history_items ON history_items.id = history_visits.history_item
+           WHERE ${where}`)
+                .get(...values);
+            return row.n;
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/connectors/SafariTransformer.d.ts

@@ -0,0 +1,8 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { ActionAndChildren } from '@chronicle.app/schema';
+export default class SafariTransformer extends ChronicleTransformer {
+    transform(record: Record): Promise<ActionAndChildren[]>;
+    private buildViewActions;
+    private buildWebPage;
+}
+//# sourceMappingURL=SafariTransformer.d.ts.map

package/dist/connectors/SafariTransformer.js

@@ -0,0 +1,36 @@
+import { ChronicleTransformer } from '@chronicle.app/etl';
+import { buildICloudPersonSchema } from '@chronicle.app/icloud';
+export default class SafariTransformer extends ChronicleTransformer {
+    async transform(record) {
+        const actions = [];
+        if (record.extraction.recordType === 'views') {
+            actions.push(...(await this.buildViewActions(record)));
+        }
+        return actions;
+    }
+    async buildViewActions(record) {
+        const actions = [];
+        const user = await buildICloudPersonSchema(record.context.account);
+        const webpage = this.buildWebPage(record);
+        // Create a ViewAction for the browser visit
+        const viewAction = {
+            '@type': 'ViewAction',
+            timestamp: new Date(record.data.unix_timestamp * 1000),
+            '@key': ['@type', 'source', 'timestamp'],
+            source: 'safari',
+            // Without an iCloud account the viewer can't be identified, so omit them.
+            ...(user && { agent: user }),
+            object: webpage,
+        };
+        actions.push(viewAction);
+        return actions;
+    }
+    buildWebPage(record) {
+        return {
+            '@type': 'Entity',
+            '@key': ['url'],
+            url: record.data.url,
+            name: record.data.title || record.data.url,
+        };
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,3 @@
+// Export extractors for plugin scanning
+export { SafariExtractor } from './connectors/SafariExtractor.js';
+export { default as SafariTransformer } from './connectors/SafariTransformer.js';

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@chronicle.app/safari",
+  "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": [],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Chronicle Safari browsing history plugin",
+  "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/safari"
+  },
+  "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": {
+      "safari": {
+        "strategies": {
+          "app-db": {
+            "delivery": "local",
+            "recordTypes": [
+              "views"
+            ],
+            "default": true
+          }
+        },
+        "platforms": [
+          "darwin"
+        ],
+        "requires": [
+          "full-disk-access"
+        ]
+      }
+    }
+  }
+}