apple-books-export 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denis Moskalets (denya.msk@gmail.com)
+
+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,83 @@
+# Apple Books Export
+
+Export all your highlights, bookmarks, and notes from Apple Books on macOS.
+
+## What is this?
+
+If you highlight books in Apple Books, this tool lets you export all your highlights to HTML, Markdown, JSON, or CSV. Perfect for:
+
+- Backing up your highlights
+- Searching through all your notes
+- Sharing quotes from books you've read
+- Importing highlights into note-taking apps
+
+## Quick Start
+
+No installation needed! Just run:
+
+```bash
+bunx apple-books-export
+```
+
+This creates an `apple-books-export.html` file with all your highlights in a searchable, interactive page.
+
+**Don't have Bun?** Install it with: `curl -fsSL https://bun.sh/install | bash`
+
+Or use Node.js instead: `npx apple-books-export`
+
+## Common Uses
+
+```bash
+# Export to searchable HTML (default)
+bunx apple-books-export
+
+# Export to Markdown files (one per book)
+bunx apple-books-export markdown
+
+# Export to a single JSON file
+bunx apple-books-export json --single-file
+
+# Export only highlights (skip bookmarks)
+bunx apple-books-export --highlights-only
+
+# Export only yellow highlights
+bunx apple-books-export --colors yellow
+```
+
+## Export Formats
+
+### HTML (default)
+Creates a single webpage with all your highlights. Includes search, color-coding, and works offline.
+
+### Markdown
+Creates readable text files with YAML metadata. Great for importing into Obsidian or Notion.
+
+### JSON
+Exports raw data with all metadata. Useful for custom processing or analysis.
+
+### CSV
+Spreadsheet format for Excel or data analysis.
+
+## Options
+
+Run `bunx apple-books-export --help` to see all options.
+
+Common options:
+- `--output <path>` - Custom output location
+- `--single-file` - Combine all books into one file (for Markdown/JSON)
+- `--highlights-only` - Skip bookmarks and notes
+- `--colors yellow,green` - Only export specific highlight colors
+
+## Troubleshooting
+
+**"Database not found"** - Make sure you have Apple Books installed and have created at least one highlight or bookmark.
+
+**No highlights exported** - Check that you're not using filters that exclude all your highlights (e.g., `--colors pink` when you only have yellow highlights).
+
+## License
+
+MIT - Free to use and modify.
+
+## Credits
+
+Built with [Bun](https://bun.sh). Inspired by [jladicos/apple-books-highlights](https://github.com/jladicos/apple-books-highlights) and [angela-zhao/apple-books-annotations-exporter](https://github.com/angela-zhao/apple-books-annotations-exporter).

package/dist/database.d.ts

@@ -0,0 +1,37 @@
+import type { Annotation, Book, RawAnnotation } from "./types.js";
+/**
+ * Convert Apple's 2001-01-01 epoch timestamp to JavaScript Date
+ */
+export declare function convertAppleDate(timestamp: number): Date;
+/**
+ * Find Apple Books SQLite database files
+ */
+export declare function findDatabases(customPaths?: {
+    annotations?: string;
+    library?: string;
+}): {
+    annotationsDb: string;
+    libraryDb: string;
+};
+/**
+ * Query all annotations with book metadata
+ */
+export declare function queryAnnotations(annotationsDbPath: string, libraryDbPath: string): Promise<RawAnnotation[]>;
+/**
+ * Transform raw annotations into structured Annotation objects
+ */
+export declare function transformAnnotations(rawAnnotations: RawAnnotation[]): Annotation[];
+/**
+ * Group annotations by book
+ */
+export declare function groupByBook(rawAnnotations: RawAnnotation[]): Book[];
+/**
+ * Filter annotations based on export options
+ */
+export declare function filterAnnotations(annotations: Annotation[], options: {
+    includeHighlights: boolean;
+    includeBookmarks: boolean;
+    includeNotes: boolean;
+    colorFilters?: string[];
+}): Annotation[];
+//# sourceMappingURL=database.d.ts.map

package/dist/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa,EAAmC,MAAM,YAAY,CAAC;AAOnG;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAMxD;AA4CD;;GAEG;AACH,wBAAgB,aAAa,CAAC,WAAW,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IACvF,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB,CAyCA;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,iBAAiB,EAAE,MAAM,EACzB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,aAAa,EAAE,CAAC,CA+B1B;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,aAAa,EAAE,GAAG,UAAU,EAAE,CAiBlF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,cAAc,EAAE,aAAa,EAAE,GAAG,IAAI,EAAE,CAkCnE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,UAAU,EAAE,EACzB,OAAO,EAAE;IACP,iBAAiB,EAAE,OAAO,CAAC;IAC3B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB,GACA,UAAU,EAAE,CAcd"}

package/dist/database.js

@@ -0,0 +1,187 @@
+import { Database } from "./db-adapter.js";
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, readdirSync } from "fs";
+const APPLE_BOOKS_CONTAINER = join(homedir(), "Library/Containers/com.apple.iBooksX/Data/Documents");
+/**
+ * Convert Apple's 2001-01-01 epoch timestamp to JavaScript Date
+ */
+export function convertAppleDate(timestamp) {
+    // Apple epoch starts at 2001-01-01 00:00:00 UTC
+    // Unix epoch starts at 1970-01-01 00:00:00 UTC
+    // Difference is 978307200 seconds
+    const APPLE_EPOCH_OFFSET = 978307200;
+    return new Date((timestamp + APPLE_EPOCH_OFFSET) * 1000);
+}
+/**
+ * Map Apple's annotation style code to type and color
+ */
+function mapAnnotationStyle(style) {
+    // Based on research:
+    // 0 = underline (highlight)
+    // 1 = green highlight
+    // 2 = blue highlight
+    // 3 = yellow highlight
+    // 4 = pink highlight
+    // 5 = purple highlight
+    const styleMap = {
+        0: { type: 'highlight', color: 'underline' },
+        1: { type: 'highlight', color: 'green' },
+        2: { type: 'highlight', color: 'blue' },
+        3: { type: 'highlight', color: 'yellow' },
+        4: { type: 'highlight', color: 'pink' },
+        5: { type: 'highlight', color: 'purple' },
+    };
+    return styleMap[style] || { type: 'highlight', color: 'yellow' };
+}
+/**
+ * Determine annotation type based on content
+ */
+function determineAnnotationType(raw) {
+    // If it has a note, it's a note annotation
+    if (raw.note && raw.note.trim().length > 0) {
+        return 'note';
+    }
+    // If it has no selected text, it's a bookmark
+    if (!raw.text || raw.text.trim().length === 0) {
+        return 'bookmark';
+    }
+    // Otherwise it's a highlight
+    return 'highlight';
+}
+/**
+ * Find Apple Books SQLite database files
+ */
+export function findDatabases(customPaths) {
+    if (customPaths?.annotations && customPaths?.library) {
+        return {
+            annotationsDb: customPaths.annotations,
+            libraryDb: customPaths.library,
+        };
+    }
+    // Find AEAnnotation database
+    const annotationsDir = join(APPLE_BOOKS_CONTAINER, "AEAnnotation");
+    if (!existsSync(annotationsDir)) {
+        throw new Error(`Annotations directory not found: ${annotationsDir}`);
+    }
+    const annotationFiles = readdirSync(annotationsDir).filter(f => f.startsWith("AEAnnotation_") && f.endsWith(".sqlite"));
+    if (annotationFiles.length === 0) {
+        throw new Error(`No annotation database found in ${annotationsDir}`);
+    }
+    const annotationsDb = join(annotationsDir, annotationFiles[0]);
+    // Find BKLibrary database
+    const libraryDir = join(APPLE_BOOKS_CONTAINER, "BKLibrary");
+    if (!existsSync(libraryDir)) {
+        throw new Error(`Library directory not found: ${libraryDir}`);
+    }
+    const libraryFiles = readdirSync(libraryDir).filter(f => f.startsWith("BKLibrary") && f.endsWith(".sqlite"));
+    if (libraryFiles.length === 0) {
+        throw new Error(`No library database found in ${libraryDir}`);
+    }
+    const libraryDb = join(libraryDir, libraryFiles[0]);
+    return { annotationsDb, libraryDb };
+}
+/**
+ * Query all annotations with book metadata
+ */
+export async function queryAnnotations(annotationsDbPath, libraryDbPath) {
+    const annotationsDb = await Database.create(annotationsDbPath, { readonly: true });
+    // Attach the library database
+    annotationsDb.run(`ATTACH DATABASE '${libraryDbPath}' AS library`);
+    const query = `
+    SELECT
+      ZAEANNOTATION.Z_PK as id,
+      ZAEANNOTATION.ZANNOTATIONASSETID as assetId,
+      ZAEANNOTATION.ZANNOTATIONSELECTEDTEXT as text,
+      ZAEANNOTATION.ZANNOTATIONNOTE as note,
+      ZAEANNOTATION.ZANNOTATIONSTYLE as style,
+      ZAEANNOTATION.ZFUTUREPROOFING5 as location,
+      ZAEANNOTATION.ZANNOTATIONCREATIONDATE as createdAt,
+      ZAEANNOTATION.ZANNOTATIONMODIFICATIONDATE as modifiedAt,
+      ZAEANNOTATION.ZANNOTATIONDELETED as deleted,
+      library.ZBKLIBRARYASSET.ZTITLE as title,
+      library.ZBKLIBRARYASSET.ZAUTHOR as author,
+      library.ZBKLIBRARYASSET.ZGENRE as genre
+    FROM ZAEANNOTATION
+    LEFT JOIN library.ZBKLIBRARYASSET
+      ON ZAEANNOTATION.ZANNOTATIONASSETID = library.ZBKLIBRARYASSET.ZASSETID
+    WHERE ZAEANNOTATION.ZANNOTATIONDELETED = 0
+    ORDER BY title, createdAt
+  `;
+    const results = annotationsDb.query(query).all();
+    annotationsDb.close();
+    return results;
+}
+/**
+ * Transform raw annotations into structured Annotation objects
+ */
+export function transformAnnotations(rawAnnotations) {
+    return rawAnnotations.map(raw => {
+        const type = determineAnnotationType(raw);
+        const { color } = mapAnnotationStyle(raw.style);
+        return {
+            id: raw.id,
+            type,
+            color,
+            text: raw.text,
+            note: raw.note,
+            location: raw.location,
+            chapter: null, // Apple Books doesn't store chapter info in accessible way
+            createdAt: convertAppleDate(raw.createdAt),
+            modifiedAt: convertAppleDate(raw.modifiedAt),
+        };
+    });
+}
+/**
+ * Group annotations by book
+ */
+export function groupByBook(rawAnnotations) {
+    const bookMap = new Map();
+    for (const raw of rawAnnotations) {
+        const assetId = raw.assetId;
+        if (!bookMap.has(assetId)) {
+            bookMap.set(assetId, {
+                assetId,
+                title: raw.title,
+                author: raw.author,
+                genre: raw.genre,
+                annotations: [],
+            });
+        }
+        const book = bookMap.get(assetId);
+        const type = determineAnnotationType(raw);
+        const { color } = mapAnnotationStyle(raw.style);
+        book.annotations.push({
+            id: raw.id,
+            type,
+            color,
+            text: raw.text,
+            note: raw.note,
+            location: raw.location,
+            chapter: null,
+            createdAt: convertAppleDate(raw.createdAt),
+            modifiedAt: convertAppleDate(raw.modifiedAt),
+        });
+    }
+    return Array.from(bookMap.values());
+}
+/**
+ * Filter annotations based on export options
+ */
+export function filterAnnotations(annotations, options) {
+    return annotations.filter(ann => {
+        // Filter by type
+        if (ann.type === 'highlight' && !options.includeHighlights)
+            return false;
+        if (ann.type === 'bookmark' && !options.includeBookmarks)
+            return false;
+        if (ann.type === 'note' && !options.includeNotes)
+            return false;
+        // Filter by color
+        if (options.colorFilters && options.colorFilters.length > 0) {
+            if (!options.colorFilters.includes(ann.color))
+                return false;
+        }
+        return true;
+    });
+}

package/dist/db-adapter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Database adapter for dual runtime support (Bun + Node.js)
+ *
+ * Provides a unified SQLite interface that works with:
+ * - Bun's built-in bun:sqlite (zero dependencies)
+ * - Node.js's better-sqlite3 (auto-installed)
+ */
+type QueryResult = any[];
+interface DatabaseInterface {
+    query(sql: string): {
+        all(): QueryResult;
+    };
+    run(sql: string): void;
+    close(): void;
+}
+/**
+ * Unified Database class that works in both Bun and Node.js
+ *
+ * This uses a factory pattern since constructors can't be async.
+ */
+export declare class Database implements DatabaseInterface {
+    private db;
+    private isBun;
+    private constructor();
+    /**
+     * Create a new Database instance (async factory)
+     */
+    static create(path: string, options?: {
+        readonly?: boolean;
+    }): Promise<Database>;
+    query(sql: string): any;
+    run(sql: string): void;
+    close(): void;
+}
+export {};
+//# sourceMappingURL=db-adapter.d.ts.map

package/dist/db-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-adapter.d.ts","sourceRoot":"","sources":["../src/db-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,KAAK,WAAW,GAAG,GAAG,EAAE,CAAC;AAEzB,UAAU,iBAAiB;IACzB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,GAAG,IAAI,WAAW,CAAA;KAAE,CAAC;IAC3C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,IAAI,IAAI,CAAC;CACf;AASD;;;;GAIG;AACH,qBAAa,QAAS,YAAW,iBAAiB;IAChD,OAAO,CAAC,EAAE,CAAM;IAChB,OAAO,CAAC,KAAK,CAAU;IAEvB,OAAO;IAKP;;OAEG;WACU,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,CAAC;IAmBtF,KAAK,CAAC,GAAG,EAAE,MAAM;IAYjB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAUtB,KAAK,IAAI,IAAI;CAGd"}

package/dist/db-adapter.js

@@ -0,0 +1,72 @@
+/**
+ * Database adapter for dual runtime support (Bun + Node.js)
+ *
+ * Provides a unified SQLite interface that works with:
+ * - Bun's built-in bun:sqlite (zero dependencies)
+ * - Node.js's better-sqlite3 (auto-installed)
+ */
+/**
+ * Detect runtime environment
+ */
+function isBunRuntime() {
+    return typeof globalThis.Bun !== "undefined";
+}
+/**
+ * Unified Database class that works in both Bun and Node.js
+ *
+ * This uses a factory pattern since constructors can't be async.
+ */
+export class Database {
+    db;
+    isBun;
+    constructor(db, isBun) {
+        this.db = db;
+        this.isBun = isBun;
+    }
+    /**
+     * Create a new Database instance (async factory)
+     */
+    static async create(path, options) {
+        const isBun = isBunRuntime();
+        if (isBun) {
+            // Bun runtime - use built-in bun:sqlite
+            // Dynamic import works in both runtimes
+            const { Database: BunDB } = await import('bun:sqlite');
+            const db = new BunDB(path, options);
+            return new Database(db, isBun);
+        }
+        else {
+            // Node.js runtime - use better-sqlite3
+            // Dynamic import works in ESM
+            const BetterSqlite3Module = await import('better-sqlite3');
+            const BetterSqlite3 = BetterSqlite3Module.default || BetterSqlite3Module;
+            const db = new BetterSqlite3(path, options);
+            return new Database(db, isBun);
+        }
+    }
+    query(sql) {
+        if (this.isBun) {
+            // Bun: db.query(sql).all()
+            return this.db.query(sql);
+        }
+        else {
+            // Node.js: db.prepare(sql).all()
+            return {
+                all: () => this.db.prepare(sql).all()
+            };
+        }
+    }
+    run(sql) {
+        if (this.isBun) {
+            // Bun: db.run(sql)
+            this.db.run(sql);
+        }
+        else {
+            // Node.js: db.prepare(sql).run()
+            this.db.prepare(sql).run();
+        }
+    }
+    close() {
+        this.db.close();
+    }
+}

package/dist/exporters/csv.d.ts

@@ -0,0 +1,6 @@
+import type { Book } from "../types.js";
+/**
+ * Export books to CSV file
+ */
+export declare function exportToCsv(books: Book[], outputPath: string): string;
+//# sourceMappingURL=csv.d.ts.map

package/dist/exporters/csv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.d.ts","sourceRoot":"","sources":["../../src/exporters/csv.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AA4BxC;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAgDrE"}

package/dist/exporters/csv.js

@@ -0,0 +1,70 @@
+import { writeFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+/**
+ * Escape CSV field value
+ */
+function escapeCsvField(value) {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    const stringValue = String(value);
+    // If the value contains quotes, commas, or newlines, it needs to be quoted
+    if (stringValue.includes('"') || stringValue.includes(',') || stringValue.includes('\n')) {
+        // Escape quotes by doubling them
+        return `"${stringValue.replace(/"/g, '""')}"`;
+    }
+    return stringValue;
+}
+/**
+ * Format date for CSV
+ */
+function formatDate(date) {
+    return date.toISOString().replace('T', ' ').substring(0, 19);
+}
+/**
+ * Export books to CSV file
+ */
+export function exportToCsv(books, outputPath) {
+    // Ensure parent directory exists
+    mkdirSync(dirname(outputPath), { recursive: true });
+    // CSV header
+    const headers = [
+        'assetId',
+        'title',
+        'author',
+        'genre',
+        'annotationId',
+        'type',
+        'color',
+        'text',
+        'note',
+        'location',
+        'chapter',
+        'createdAt',
+        'modifiedAt',
+    ];
+    let csv = headers.join(',') + '\n';
+    // Add rows
+    for (const book of books) {
+        for (const annotation of book.annotations) {
+            const row = [
+                escapeCsvField(book.assetId),
+                escapeCsvField(book.title),
+                escapeCsvField(book.author),
+                escapeCsvField(book.genre),
+                escapeCsvField(String(annotation.id)),
+                escapeCsvField(annotation.type),
+                escapeCsvField(annotation.color),
+                escapeCsvField(annotation.text),
+                escapeCsvField(annotation.note),
+                escapeCsvField(annotation.location),
+                escapeCsvField(annotation.chapter),
+                escapeCsvField(formatDate(annotation.createdAt)),
+                escapeCsvField(formatDate(annotation.modifiedAt)),
+            ];
+            csv += row.join(',') + '\n';
+        }
+    }
+    writeFileSync(outputPath, csv, 'utf-8');
+    return outputPath;
+}

package/dist/exporters/html.d.ts

@@ -0,0 +1,3 @@
+import type { Book } from '../types.js';
+export declare function exportToHtml(books: Book[], outputPath: string): string;
+//# sourceMappingURL=html.d.ts.map

package/dist/exporters/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../src/exporters/html.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,aAAa,CAAC;AAqHpD,wBAAgB,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CA+qBtE"}