@chronicle.app/zotero 0.3.0

package/dist/connectors/ZoteroExtractor.js

@@ -0,0 +1,551 @@
+import { SystemInfo } from '@chronicle.app/etl';
+import { SqliteExtractor, timeRangeConditions, iterateRows } from '@chronicle.app/etl-sqlite';
+import { DatabaseSync } from 'node:sqlite';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants as fsConstants, copyFileSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, isAbsolute, join } from 'node:path';
+import { z } from 'zod';
+import ZoteroTransformer from './ZoteroTransformer.js';
+/** Zotero's UTC `YYYY-MM-DD HH:MM:SS` form, so string comparison against `dateModified` is correct. */
+function toSqliteTimestamp(d) {
+    return d.toISOString().slice(0, 19).replace('T', ' ');
+}
+function isSqliteBusy(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        // node:sqlite reports the SQLite result code as `errcode` (possibly an
+        // extended code, whose low byte is the primary code); 5 is SQLITE_BUSY.
+        (err.errcode ?? 0) % 256 === 5);
+}
+/**
+ * A local Zotero library — works (references), the highlights and notes made
+ * on their attachments, standalone attachments filed without a parent work,
+ * and note items written on a work or standing alone. Reads `zotero.sqlite`
+ * directly; the user library only (group libraries are out of scope),
+ * excluding anything in the trash.
+ */
+export class ZoteroExtractor extends SqliteExtractor {
+    static source = 'zotero';
+    static description = 'Works, highlights, notes, and reading activity';
+    static delivery = 'local';
+    static strategy = 'app-db';
+    static recordTypes = ['works', 'annotations', 'attachments', 'notes'];
+    static default = true;
+    static defaultTransformer = ZoteroTransformer;
+    // Re-reads the library's current state on every run — fields, tags,
+    // collections, and creators are all mutable in place — so attributes are
+    // sighted at read time rather than back-dated to dateAdded/dateModified.
+    // See Extractor.temporality.
+    static temporality = 'snapshot';
+    static schema = SqliteExtractor.schema.omit({ input: true }).extend({
+        input: z
+            .string()
+            .describe('Path to the Zotero data directory (contains zotero.sqlite and storage/)')
+            .default(join(homedir(), 'Zotero')),
+    });
+    dataDir;
+    localUserKey;
+    library;
+    machine;
+    dbMtime;
+    extractedCount = 0;
+    /** Set when Zotero's lock forced a filesystem-level clone; cleaned up in teardown(). */
+    tempDbPath;
+    /** Item keys of child attachments whose carrier (path or content hash) is shared with a different parent work; rebuilt per extract() run. */
+    flaggedAttachmentKeys;
+    /**
+     * The item's 8-char Zotero key. Every record type (work, annotation,
+     * attachment, note) is an `items` row, and the key is unique across all of
+     * them within a library — the same field each transformer keyset uses.
+     */
+    keyOf(record) {
+        return record.data.key ?? null;
+    }
+    async setup() {
+        const { input } = this.config;
+        this.dataDir = input.endsWith('.sqlite') ? dirname(input) : input;
+        const dbPath = input.endsWith('.sqlite') ? input : join(this.dataDir, 'zotero.sqlite');
+        // From the ORIGINAL file, even when the busy fallback below reads a
+        // freshly-made copy instead — the copy's mtime is just "now" and would
+        // defeat the byte-identical-on-unchanged-library property of asOfTime().
+        this.dbMtime = statSync(dbPath).mtime;
+        // Zotero uses journal_mode=delete, so a plain readonly open reads a
+        // consistent snapshot without contending with a running Zotero instance.
+        // Never opened read-write: the library must never be disturbed.
+        this.db = new DatabaseSync(dbPath, { readOnly: true });
+        try {
+            this.localUserKey = this.readLocalUserKey(dbPath);
+        }
+        catch (error) {
+            if (!isSqliteBusy(error))
+                throw error;
+            // Zotero holds the database in exclusive locking mode for its entire
+            // run, so a readonly open can never read while it's open (the open
+            // itself acquires no lock — the first real query is where this
+            // surfaces). Fall back to a filesystem-level clone: with
+            // journal_mode=delete the file is consistent except during the brief
+            // window of an active write, so a clone of the closed-journal db
+            // (instant on APFS via COPYFILE_FICLONE, a plain copy elsewhere) is
+            // consistent in practice. The clone is disposable, removed in
+            // teardown().
+            this.db.close();
+            this.tempDbPath = join(tmpdir(), `zotero-${randomUUID()}.sqlite`);
+            copyFileSync(dbPath, this.tempDbPath, fsConstants.COPYFILE_FICLONE);
+            this.db = new DatabaseSync(this.tempDbPath, { readOnly: true });
+            this.localUserKey = this.readLocalUserKey(this.tempDbPath);
+        }
+        // The zotero.org userID is globally stable and identical on every machine
+        // syncing this library, so it wins as the scope handle when present; a
+        // library that has never synced has no userID, so the install-local
+        // localUserKey is the only handle available and becomes the scope.
+        this.library = this.readUserID() ?? this.localUserKey;
+        this.machine = (await SystemInfo.getInstance()).getMachineName();
+    }
+    readLocalUserKey(dbPath) {
+        const row = this.db.prepare(`SELECT value FROM settings WHERE setting = 'account' AND key = 'localUserKey'`).get();
+        if (!row?.value) {
+            throw new Error(`No settings.account.localUserKey in ${dbPath} — is this a Zotero data directory? (the key exists even without a zotero.org account)`);
+        }
+        return row.value;
+    }
+    readUserID() {
+        const row = this.db.prepare(`SELECT value FROM settings WHERE setting = 'account' AND key = 'userID'`).get();
+        return row?.value === null || row?.value === undefined ? undefined : String(row.value);
+    }
+    async teardown() {
+        await super.teardown();
+        if (this.tempDbPath) {
+            rmSync(this.tempDbPath, { force: true });
+            this.tempDbPath = undefined;
+        }
+    }
+    // The DB file's own mtime, not the run start: an unchanged library re-reads
+    // the same "as of" time on every run, so the emitted records are
+    // byte-identical and the store's ingest is a no-op; an edited library moves
+    // the mtime forward, and every record is genuinely re-sighted then.
+    asOfTime() {
+        return this.dbMtime;
+    }
+    async *extract() {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        this.extractedCount = 0;
+        this.flaggedAttachmentKeys = this.buildFlaggedAttachmentKeys();
+        const collections = this.loadCollections();
+        yield* this.iterateWorks(collections);
+        yield* this.iterateAnnotations();
+        yield* this.iterateOrphanAttachments(collections);
+        yield* this.iterateNotes();
+    }
+    /** The since/until window over a `dateModified` column, as ` AND …` terms appended to each stream's WHERE. */
+    sinceUntilFilter(column) {
+        const { conditions, values } = timeRangeConditions(column, this.config, {
+            convert: toSqliteTimestamp,
+            sinceOp: '>=',
+            untilOp: '<=',
+        });
+        return {
+            clause: conditions.map(c => ` AND ${c}`).join(''),
+            params: values,
+        };
+    }
+    *iterateWorks(collections) {
+        const { clause, params } = this.sinceUntilFilter('i.dateModified');
+        const sql = `
+      SELECT i.itemID AS itemID, i.key AS key, i.dateAdded AS dateAdded, i.dateModified AS dateModified,
+             it.typeName AS itemType
+      FROM items i
+      JOIN itemTypes it ON it.itemTypeID = i.itemTypeID
+      JOIN libraries l ON l.libraryID = i.libraryID
+      WHERE l.type = 'user'
+        AND i.itemID NOT IN (SELECT itemID FROM deletedItems)
+        AND it.typeName NOT IN ('attachment', 'annotation', 'note')${clause}
+      ORDER BY i.dateModified DESC`;
+        for (const row of iterateRows(this.db.prepare(sql), ...params)) {
+            if (this.shouldStopExtracting(this.extractedCount))
+                return;
+            const data = {
+                key: row.key,
+                itemType: row.itemType,
+                dateAdded: row.dateAdded,
+                dateModified: row.dateModified,
+                fields: this.loadFields(row.itemID),
+                creators: this.loadCreators(row.itemID),
+                collections: this.getItemCollections(row.itemID, collections),
+                tags: this.loadTags(row.itemID),
+                attachments: this.loadWorkAttachments(row.itemID),
+            };
+            this.extractedCount++;
+            yield this.createRecord(data, {
+                recordType: 'works',
+                localUserKey: this.localUserKey,
+                library: this.library,
+                machine: this.machine,
+            });
+        }
+    }
+    *iterateAnnotations() {
+        const { clause, params } = this.sinceUntilFilter('i.dateModified');
+        const sql = `
+      SELECT i.itemID AS itemID, i.key AS key, i.dateAdded AS dateAdded, i.dateModified AS dateModified,
+             a.type AS type, a.authorName AS authorName, a.text AS text, a.comment AS comment,
+             a.color AS color, a.pageLabel AS pageLabel, a.sortIndex AS sortIndex, a.position AS position,
+             a.isExternal AS isExternal,
+             ai.itemID AS attItemID, ai.key AS attKey, ai.dateAdded AS attDateAdded,
+             att.parentItemID AS workItemID, att.linkMode AS attLinkMode, att.contentType AS attContentType,
+             att.path AS attPath, att.lastRead AS attLastRead
+      FROM itemAnnotations a
+      JOIN items i ON i.itemID = a.itemID
+      JOIN libraries l ON l.libraryID = i.libraryID
+      JOIN itemAttachments att ON att.itemID = a.parentItemID
+      JOIN items ai ON ai.itemID = att.itemID
+      WHERE l.type = 'user'
+        AND i.itemID NOT IN (SELECT itemID FROM deletedItems)
+        AND ai.itemID NOT IN (SELECT itemID FROM deletedItems)
+        AND (att.parentItemID IS NULL OR att.parentItemID NOT IN (SELECT itemID FROM deletedItems))${clause}
+      ORDER BY i.dateModified DESC`;
+        for (const row of iterateRows(this.db.prepare(sql), ...params)) {
+            if (this.shouldStopExtracting(this.extractedCount))
+                return;
+            const attachment = this.buildAttachment({
+                itemID: row.attItemID,
+                key: row.attKey,
+                dateAdded: row.attDateAdded,
+                parentItemID: row.workItemID,
+                linkMode: row.attLinkMode,
+                contentType: row.attContentType,
+                path: row.attPath,
+                lastRead: row.attLastRead,
+            });
+            const work = this.loadWorkRef(row.workItemID);
+            const data = {
+                key: row.key,
+                type: row.type,
+                text: row.text,
+                comment: row.comment,
+                color: row.color,
+                pageLabel: row.pageLabel,
+                sortIndex: row.sortIndex,
+                position: row.position,
+                isExternal: row.isExternal,
+                authorName: row.authorName,
+                dateAdded: row.dateAdded,
+                dateModified: row.dateModified,
+                attachment,
+                ...(work ? { work } : {}),
+            };
+            this.extractedCount++;
+            yield this.createRecord(data, {
+                recordType: 'annotations',
+                localUserKey: this.localUserKey,
+                library: this.library,
+                machine: this.machine,
+            });
+        }
+    }
+    *iterateOrphanAttachments(collections) {
+        const { clause, params } = this.sinceUntilFilter('i.dateModified');
+        const sql = `
+      SELECT i.itemID AS itemID, i.key AS key, i.dateAdded AS dateAdded, i.dateModified AS dateModified,
+             att.parentItemID AS parentItemID, att.linkMode AS linkMode, att.contentType AS contentType,
+             att.path AS path, att.lastRead AS lastRead
+      FROM itemAttachments att
+      JOIN items i ON i.itemID = att.itemID
+      JOIN libraries l ON l.libraryID = i.libraryID
+      WHERE l.type = 'user'
+        AND att.parentItemID IS NULL
+        AND i.itemID NOT IN (SELECT itemID FROM deletedItems)${clause}
+      ORDER BY i.dateModified DESC`;
+        for (const row of iterateRows(this.db.prepare(sql), ...params)) {
+            if (this.shouldStopExtracting(this.extractedCount))
+                return;
+            const data = {
+                ...this.buildAttachment(row),
+                dateModified: row.dateModified,
+                tags: this.loadTags(row.itemID),
+                collections: this.getItemCollections(row.itemID, collections),
+            };
+            this.extractedCount++;
+            yield this.createRecord(data, {
+                recordType: 'attachments',
+                localUserKey: this.localUserKey,
+                library: this.library,
+                machine: this.machine,
+            });
+        }
+    }
+    *iterateNotes() {
+        const { clause, params } = this.sinceUntilFilter('i.dateModified');
+        const sql = `
+      SELECT i.itemID AS itemID, i.key AS key, i.dateAdded AS dateAdded, i.dateModified AS dateModified,
+             n.parentItemID AS parentItemID, n.note AS note, n.title AS title
+      FROM items i
+      JOIN itemTypes it ON it.itemTypeID = i.itemTypeID
+      JOIN itemNotes n ON n.itemID = i.itemID
+      JOIN libraries l ON l.libraryID = i.libraryID
+      WHERE l.type = 'user'
+        AND it.typeName = 'note'
+        AND i.itemID NOT IN (SELECT itemID FROM deletedItems)
+        AND (n.parentItemID IS NULL OR n.parentItemID NOT IN (SELECT itemID FROM deletedItems))${clause}
+      ORDER BY i.dateModified DESC`;
+        for (const row of iterateRows(this.db.prepare(sql), ...params)) {
+            if (this.shouldStopExtracting(this.extractedCount))
+                return;
+            const work = this.loadWorkRef(row.parentItemID);
+            const data = {
+                key: row.key,
+                title: row.title,
+                note: row.note,
+                dateAdded: row.dateAdded,
+                dateModified: row.dateModified,
+                ...(work ? { work } : {}),
+            };
+            this.extractedCount++;
+            yield this.createRecord(data, {
+                recordType: 'notes',
+                localUserKey: this.localUserKey,
+                library: this.library,
+                machine: this.machine,
+            });
+        }
+    }
+    buildAttachment(row) {
+        const fields = this.loadFields(row.itemID);
+        const attachment = {
+            key: row.key,
+            linkMode: row.linkMode,
+            contentType: row.contentType,
+            path: row.path,
+            dateAdded: row.dateAdded,
+        };
+        const resolvedPath = this.resolveAttachmentPath(row.key, row.linkMode, row.path);
+        if (resolvedPath)
+            attachment.resolvedPath = resolvedPath;
+        if (fields.title)
+            attachment.title = fields.title;
+        if (fields.url)
+            attachment.url = fields.url;
+        if (row.lastRead !== null)
+            attachment.lastRead = row.lastRead;
+        // Orphans never carry the flag: flaggedAttachmentKeys only ever contains
+        // keys collected from children (see buildFlaggedAttachmentKeys), but the
+        // parentItemID check is kept here too so that stays true by construction,
+        // not by coincidence.
+        if (row.parentItemID !== null && this.flaggedAttachmentKeys.has(row.key)) {
+            attachment.sharedCarrier = true;
+        }
+        return attachment;
+    }
+    /**
+     * Item keys of child attachments whose carrier — resolved path, or file
+     * content hash — also appears under a DIFFERENT parent work. Built from
+     * every non-deleted attachment in the user library (children and orphans),
+     * but only children contribute to (and can be flagged by) the map: an
+     * orphan has no parent to weld two works through.
+     */
+    buildFlaggedAttachmentKeys() {
+        const rows = this.db.prepare(`SELECT i.key AS key, att.parentItemID AS parentItemID, att.linkMode AS linkMode, att.path AS path
+       FROM itemAttachments att
+       JOIN items i ON i.itemID = att.itemID
+       JOIN libraries l ON l.libraryID = i.libraryID
+       WHERE l.type = 'user'
+         AND i.itemID NOT IN (SELECT itemID FROM deletedItems)`).all();
+        const carriers = rows.map(row => ({
+            key: row.key,
+            parentItemID: row.parentItemID,
+            carrierKeys: this.carrierKeys(row.key, row.linkMode, row.path),
+        }));
+        const carrierMap = new Map();
+        for (const c of carriers) {
+            if (c.parentItemID === null)
+                continue; // orphans don't count as parents
+            for (const k of c.carrierKeys) {
+                const parents = carrierMap.get(k) ?? new Set();
+                parents.add(c.parentItemID);
+                carrierMap.set(k, parents);
+            }
+        }
+        const flagged = new Set();
+        for (const c of carriers) {
+            if (c.parentItemID === null)
+                continue;
+            if (c.carrierKeys.some(k => (carrierMap.get(k)?.size ?? 0) >= 2)) {
+                flagged.add(c.key);
+            }
+        }
+        if (flagged.size > 0) {
+            this.logger.verboseInfo(`${flagged.size} attachment(s) share a carrier with a different parent work`);
+        }
+        return flagged;
+    }
+    /** The resolved path, plus a content-hash key when the file is readable — the two ways two attachments can carry the same bytes. */
+    carrierKeys(key, linkMode, path) {
+        const resolvedPath = this.resolveAttachmentPath(key, linkMode, path);
+        if (!resolvedPath)
+            return [];
+        const keys = [resolvedPath];
+        const hash = this.hashFile(resolvedPath);
+        if (hash)
+            keys.push(`md5:${hash}`);
+        return keys;
+    }
+    hashFile(path) {
+        try {
+            return createHash('md5').update(readFileSync(path)).digest('hex');
+        }
+        catch {
+            return undefined; // unreadable or missing — skip silently
+        }
+    }
+    /** Storage folders are named by the attachment's own key, not its filename. */
+    resolveAttachmentPath(key, linkMode, path) {
+        if (!path)
+            return undefined;
+        if (path.startsWith('storage:')) {
+            return join(this.dataDir, 'storage', key, path.slice('storage:'.length));
+        }
+        if (linkMode === 2 && isAbsolute(path)) {
+            return path;
+        }
+        return undefined;
+    }
+    loadWorkRef(workItemID) {
+        // The work's own trashed state is already excluded by the annotation
+        // query's join condition, so a non-null id here is always live.
+        if (workItemID === null)
+            return undefined;
+        const row = this.db.prepare(`SELECT i.key AS key, it.typeName AS itemType
+         FROM items i
+         JOIN itemTypes it ON it.itemTypeID = i.itemTypeID
+         WHERE i.itemID = ?`).get(workItemID);
+        if (!row)
+            return undefined;
+        const ref = { key: row.key, itemType: row.itemType };
+        const { title } = this.loadFields(workItemID);
+        if (title)
+            ref.title = title;
+        return ref;
+    }
+    loadWorkAttachments(workItemID) {
+        const rows = this.db.prepare(`SELECT i.itemID AS itemID, i.key AS key, i.dateAdded AS dateAdded,
+                att.parentItemID AS parentItemID, att.linkMode AS linkMode, att.contentType AS contentType,
+                att.path AS path, att.lastRead AS lastRead
+         FROM itemAttachments att
+         JOIN items i ON i.itemID = att.itemID
+         WHERE att.parentItemID = ?
+           AND i.itemID NOT IN (SELECT itemID FROM deletedItems)`).all(workItemID);
+        return rows.map(row => this.buildAttachment(row));
+    }
+    loadFields(itemID) {
+        const rows = this.db.prepare(`SELECT f.fieldName AS fieldName, v.value AS value
+         FROM itemData d
+         JOIN fields f ON f.fieldID = d.fieldID
+         JOIN itemDataValues v ON v.valueID = d.valueID
+         WHERE d.itemID = ?`).all(itemID);
+        const fields = {};
+        for (const row of rows)
+            fields[row.fieldName] = row.value;
+        return fields;
+    }
+    loadCreators(itemID) {
+        return this.db.prepare(`SELECT c.firstName AS firstName, c.lastName AS lastName, c.fieldMode AS fieldMode,
+                ct.creatorType AS creatorType, ic.orderIndex AS orderIndex
+         FROM itemCreators ic
+         JOIN creators c ON c.creatorID = ic.creatorID
+         JOIN creatorTypes ct ON ct.creatorTypeID = ic.creatorTypeID
+         WHERE ic.itemID = ?
+         ORDER BY ic.orderIndex`).all(itemID);
+    }
+    loadTags(itemID) {
+        return this.db.prepare(`SELECT t.name AS name, itag.type AS type
+         FROM itemTags itag
+         JOIN tags t ON t.tagID = itag.tagID
+         WHERE itag.itemID = ?`).all(itemID);
+    }
+    loadCollections() {
+        const rows = this.db.prepare(`SELECT c.collectionID AS collectionID, c.key AS key, c.collectionName AS name,
+                c.parentCollectionID AS parentCollectionID
+         FROM collections c
+         JOIN libraries l ON l.libraryID = c.libraryID
+         WHERE l.type = 'user'`).all();
+        return new Map(rows.map(row => [row.collectionID, row]));
+    }
+    buildCollectionChain(collectionID, collections, seen = new Set()) {
+        if (seen.has(collectionID))
+            return undefined; // guard against a cyclical parent chain
+        seen.add(collectionID);
+        const row = collections.get(collectionID);
+        if (!row)
+            return undefined;
+        const parent = row.parentCollectionID === null
+            ? undefined
+            : this.buildCollectionChain(row.parentCollectionID, collections, seen);
+        return { key: row.key, name: row.name, ...(parent ? { parent } : {}) };
+    }
+    getItemCollections(itemID, collections) {
+        const rows = this.db.prepare(`SELECT collectionID FROM collectionItems WHERE itemID = ?`).all(itemID);
+        const result = [];
+        for (const row of rows) {
+            const chain = this.buildCollectionChain(row.collectionID, collections);
+            if (chain)
+                result.push(chain);
+        }
+        return result;
+    }
+    async determineCount() {
+        if (!this.db)
+            return null;
+        try {
+            const worksFilter = this.sinceUntilFilter('i.dateModified');
+            const works = this.db
+                .prepare(`SELECT COUNT(*) AS n
+           FROM items i
+           JOIN itemTypes it ON it.itemTypeID = i.itemTypeID
+           JOIN libraries l ON l.libraryID = i.libraryID
+           WHERE l.type = 'user'
+             AND i.itemID NOT IN (SELECT itemID FROM deletedItems)
+             AND it.typeName NOT IN ('attachment', 'annotation', 'note')${worksFilter.clause}`)
+                .get(...worksFilter.params);
+            const annotationsFilter = this.sinceUntilFilter('i.dateModified');
+            const annotations = this.db
+                .prepare(`SELECT COUNT(*) AS n
+           FROM itemAnnotations a
+           JOIN items i ON i.itemID = a.itemID
+           JOIN libraries l ON l.libraryID = i.libraryID
+           JOIN itemAttachments att ON att.itemID = a.parentItemID
+           JOIN items ai ON ai.itemID = att.itemID
+           WHERE l.type = 'user'
+             AND i.itemID NOT IN (SELECT itemID FROM deletedItems)
+             AND ai.itemID NOT IN (SELECT itemID FROM deletedItems)
+             AND (att.parentItemID IS NULL OR att.parentItemID NOT IN (SELECT itemID FROM deletedItems))${annotationsFilter.clause}`)
+                .get(...annotationsFilter.params);
+            const attachmentsFilter = this.sinceUntilFilter('i.dateModified');
+            const attachments = this.db
+                .prepare(`SELECT COUNT(*) AS n
+           FROM itemAttachments att
+           JOIN items i ON i.itemID = att.itemID
+           JOIN libraries l ON l.libraryID = i.libraryID
+           WHERE l.type = 'user'
+             AND att.parentItemID IS NULL
+             AND i.itemID NOT IN (SELECT itemID FROM deletedItems)${attachmentsFilter.clause}`)
+                .get(...attachmentsFilter.params);
+            const notesFilter = this.sinceUntilFilter('i.dateModified');
+            const notes = this.db
+                .prepare(`SELECT COUNT(*) AS n
+           FROM items i
+           JOIN itemTypes it ON it.itemTypeID = i.itemTypeID
+           JOIN itemNotes n ON n.itemID = i.itemID
+           JOIN libraries l ON l.libraryID = i.libraryID
+           WHERE l.type = 'user'
+             AND it.typeName = 'note'
+             AND i.itemID NOT IN (SELECT itemID FROM deletedItems)
+             AND (n.parentItemID IS NULL OR n.parentItemID NOT IN (SELECT itemID FROM deletedItems))${notesFilter.clause}`)
+                .get(...notesFilter.params);
+            return works.n + annotations.n + attachments.n + notes.n;
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/connectors/ZoteroTransformer.d.ts

@@ -0,0 +1,139 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { ActionAndChildren } from '@chronicle.app/schema';
+/**
+ * A local Zotero library (`zotero.sqlite`) → Chronicle JSON-LD.
+ *
+ * Four record shapes come off the extractor: `work` (a reference item with
+ * its creators/collections/tags/attachments joined in), `annotation` (a
+ * highlight/note made in the reader, with its attachment and parent work
+ * context), `attachment` (an orphan file saved directly to the library, with
+ * no parent work), and `note` (an HTML note item, on a work or standalone).
+ * All four are re-read on every crawl (`snapshot` temporality), so mutable
+ * attributes — collection membership, tags, the last-read timestamp — are
+ * sighted at crawl time, not back-dated.
+ */
+export default class ZoteroTransformer extends ChronicleTransformer {
+    static source: string;
+    transform(record: Record): Promise<ActionAndChildren[]>;
+    /**
+     * The library owner. The Zotero DB carries no name for the local user, only
+     * the install-stable `localUserKey`, so that's the whole identity. Not
+     * realm-scoped: a person is not a per-library thing.
+     */
+    private buildAgent;
+    /**
+     * The library's scope realm. Zotero item keys are only per-library unique,
+     * so every item-keyed entity below (works, attachments, Quotations,
+     * Comments, Collections) carries this in both its `@key` and `inRealm` —
+     * the obsidian note-key precedent, applied to a db-local id instead of a
+     * filename.
+     */
+    private buildRealm;
+    private buildWorkActions;
+    /**
+     * `lastRead` is a single overwritten "last opened" timestamp, not an
+     * append-only log — key the timestamp itself in so each newly sighted
+     * value lands as its own event instead of one event that moves in place.
+     * It's `ViewAction`, not `ReadAction`: `ReadAction` opens a `consuming` run
+     * that only a `CompleteAction` closes, and Zotero has no completion signal
+     * — a `ReadAction` here would strand the work in an eternal
+     * "currently reading" state. A single sighted open is one-shot
+     * consumption; `ViewAction` is its honest weight.
+     */
+    private buildViewAction;
+    private buildWorkEntity;
+    private buildPublisher;
+    /**
+     * Creators ordered by `orderIndex`. `author` credits the primary authors;
+     * `editor`/`translator`/`contributor` (and any other credited role Zotero
+     * reports) land in the generic `creator` bucket; `seriesEditor` is skipped
+     * outright — it credits the series, not this work.
+     */
+    private buildCreators;
+    /** fieldMode 0 = two-field person; fieldMode 1 = single-field institution (name in lastName). */
+    private buildCreatorNode;
+    /**
+     * Protocol `sameAs` edges (the goodreads idiom): each is an entity in the
+     * other namespace, keyed there — type-free, since a DOI/ISBN/arXiv/PubMed
+     * id names one work however a source typed it — carrying the work's title
+     * as name so the edge still identifies the work if it's what mints it.
+     * ISSN is handled separately (`buildPeriodical`) — it identifies the
+     * periodical, not the work itself.
+     */
+    private buildWorkSameAs;
+    /**
+     * The DOI `sameAs` edge. Its own resolver url mints the url hub, so a
+     * browser visit to the DOI link folds onto the work.
+     */
+    private buildDoiEdge;
+    /** ISBN `sameAs` edges — the field can hold several space-separated ISBNs. */
+    private buildIsbnEdges;
+    /**
+     * arXiv `sameAs` edges, mined from up to three places and deduped by id:
+     * `archiveID` (an `arXiv:<id>` prefix, or a bare id when `repository` says
+     * arXiv), an `arXiv:<id>` line in the free-text `extra` field, and an
+     * arXiv-minted DOI (`10.48550/arxiv.<id>`).
+     */
+    private buildArxivSameAs;
+    /**
+     * PMID/PMCID `sameAs` edges, mined from `PMID: <digits>` / `PMCID:
+     * PMC<digits>` lines in the free-text `extra` field.
+     */
+    private buildPubmedSameAs;
+    private buildWorkIsPartOf;
+    /**
+     * The containing book of a bookSection, name-keyed (cross-library merge by
+     * title is fine — same idiom as the periodical/series below) and carrying
+     * the section's ISBN as its own `sameAs` edges, since that ISBN identifies
+     * the book, not the section. No bookTitle → nothing honest to key the book
+     * on, so the ISBN is dropped entirely (see buildWorkSameAs).
+     */
+    private buildContainingBook;
+    /** The journal/magazine a work ran in. ISSN identifies IT, not the work. Name-keyed — not realm-scoped, cross-library merge by name is fine. */
+    private buildPeriodical;
+    /** A Zotero collection, realm-scoped (per-library keys), with its ancestor chain carried as nested `isPartOf`. */
+    private buildCollectionNode;
+    private buildTags;
+    /**
+     * A child attachment as a SPARSE facet of its work, not a separate entity
+     * (option B): the file merges INTO the work via `sameAs`, so it carries no
+     * `name` of its own — the merged entity's name comes uncontested from the
+     * work facet. `sameAs` is the collapsing edge — the work ref, plus the
+     * filesystem node when this copy has one — replacing `instanceOf`, which
+     * this transformer no longer emits anywhere.
+     */
+    private buildFileFacet;
+    /**
+     * A sparse reference to the file facet — used off the annotation record
+     * (Quotation.isPartOf, the comment-only `about` fallback) so an anchored
+     * selector records which copy it's valid in. No name (sparse, like the
+     * facet); carries `sameAs: [work ref]` so an annotation arriving before
+     * its work record still witnesses the merge.
+     */
+    private buildFileFacetRef;
+    private buildFilesystemSameAs;
+    /** A slim, typed, named, realm-scoped reference to a work — used off actions that don't own the work's full state. */
+    private buildWorkRef;
+    /** A slim, typed, named, realm-scoped reference to an attachment (orphan-annotation subject, standalone-attachment ref). */
+    private buildAttachmentRef;
+    private buildAnnotationActions;
+    /** Parses the raw `position` JSON defensively; omits the selector on any failure or unrecognized shape. */
+    private buildSelector;
+    private buildOrphanAttachmentActions;
+    /**
+     * A standalone (orphan) attachment: unlike a child attachment it IS the
+     * catalog item, not a facet of anything — its own named entity (via the
+     * display-name heuristic), unconditional filesystem `sameAs` (orphans
+     * never set `sharedCarrier`), plus its own collections/tags.
+     */
+    private buildStandaloneAttachmentEntity;
+    /**
+     * A Zotero note item — an HTML note written on a work (child) or standing
+     * alone in the library — becomes an AnnotateAction over a Comment. Unlike
+     * a highlight-comment (which shares its parent annotation's key), this
+     * Comment is keyed on the note item's OWN key; the keyset shape is
+     * identical either way, so there's no collision.
+     */
+    private buildNoteActions;
+}
+//# sourceMappingURL=ZoteroTransformer.d.ts.map