@chronicle.app/marvin 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,32 @@
+# @chronicle.app/marvin
+
+Chronicle plugin for reading sessions and annotations from Marvin, the e-reader app.
+It reads the CSV files Marvin exports. Pass the file with `--input` and pick the
+record type with `--type`:
+
+```sh
+chronicle extract marvin --type reading-sessions --input sessions.csv
+chronicle extract marvin --type annotations --input annotations.csv
+```
+
+Each type reads its own export file. The reading-sessions export has one row per
+part of a session (`Session ID`, `Book Title`, `Book Author`, `Date Created`,
+`Part Time` in seconds). Rows are grouped by session: part times are summed and the
+latest `Date Created` ends the session. Each session becomes a `ReadAction` whose
+`startTime` is the end time minus the total part time, with the `Book` as its
+`object`. Sessions come out oldest first. The limit also caps the CSV rows read
+before grouping, so pass `--limit 0` to read a whole export.
+
+The annotations export has one row per highlight or note (`ID`, `Title`, `Author`,
+`Date` or `Created`, `HighlightText`, `EntryText`). A highlight becomes a
+`QuoteAction` whose `result` is a `Quotation` that is part of the `Book`. A note
+becomes an `AnnotateAction` whose `result` is a `Comment` about the highlight, or
+about the book when the row has no highlight. Rows with neither are skipped.
+
+Books have no IDs in the export, so a `Book` is keyed by its title and its author's
+name. Marvin escapes commas in author names as `\,`; they are unescaped. The export
+does not identify the reader, so the agent is the `marvin` self person, marked as
+you with `sameAs: ['@me']`.
+
+Tests use small synthetic CSV files with made-up books and quotes, and never read
+the host's data or accounts.

package/dist/connectors/MarvinAnnotationsExtractor.d.ts

@@ -0,0 +1,10 @@
+import { Record } from '@chronicle.app/etl';
+import { MarvinExtractor } from './MarvinExtractor.js';
+import MarvinTransformer from './marvin-transformer.js';
+export declare class MarvinAnnotationsExtractor extends MarvinExtractor {
+    static description: string;
+    static recordTypes: string[];
+    static defaultTransformer: typeof MarvinTransformer;
+    extract(): AsyncGenerator<Record>;
+}
+//# sourceMappingURL=MarvinAnnotationsExtractor.d.ts.map

package/dist/connectors/MarvinAnnotationsExtractor.js

@@ -0,0 +1,24 @@
+import { MarvinExtractor } from './MarvinExtractor.js';
+import MarvinTransformer from './marvin-transformer.js';
+export class MarvinAnnotationsExtractor extends MarvinExtractor {
+    static description = 'Highlights and annotations';
+    static recordTypes = ['annotations'];
+    static defaultTransformer = MarvinTransformer;
+    async *extract() {
+        // Read all CSV rows and yield as annotation records
+        let count = 0;
+        for await (const record of super.extract()) {
+            const annotation = record.data;
+            // Filter out entries without meaningful content
+            if (!annotation.EntryText && !annotation.HighlightText) {
+                continue;
+            }
+            // Apply limit if specified
+            if (this.shouldStopExtracting(count)) {
+                break;
+            }
+            yield this.createRecord(annotation);
+            count++;
+        }
+    }
+}

package/dist/connectors/MarvinExtractor.d.ts

@@ -0,0 +1,11 @@
+import { CsvExtractor } from '@chronicle.app/etl';
+/**
+ * Base class for Marvin extractors providing shared functionality
+ */
+export declare abstract class MarvinExtractor extends CsvExtractor {
+    static source: string;
+    static delivery: "export";
+    static strategy: string;
+    constructor(config: any);
+}
+//# sourceMappingURL=MarvinExtractor.d.ts.map

package/dist/connectors/MarvinExtractor.js

@@ -0,0 +1,19 @@
+import { CsvExtractor, configForIo } from '@chronicle.app/etl';
+/**
+ * Base class for Marvin extractors providing shared functionality
+ */
+export class MarvinExtractor extends CsvExtractor {
+    static source = 'marvin';
+    static delivery = 'export';
+    static strategy = 'csv';
+    constructor(config) {
+        // Transform input flag to IoSchema format
+        const ioConfig = configForIo(config);
+        super({
+            ...config,
+            ...ioConfig,
+            columns: true, // Ensure we use first line as headers
+            trimColumns: true, // Trim whitespace from column names
+        });
+    }
+}

package/dist/connectors/MarvinSessionsExtractor.d.ts

@@ -0,0 +1,11 @@
+import { Record } from '@chronicle.app/etl';
+import { MarvinExtractor } from './MarvinExtractor.js';
+import MarvinTransformer from './marvin-transformer.js';
+export declare class MarvinSessionsExtractor extends MarvinExtractor {
+    static description: string;
+    static recordTypes: string[];
+    static default: boolean;
+    static defaultTransformer: typeof MarvinTransformer;
+    extract(): AsyncGenerator<Record>;
+}
+//# sourceMappingURL=MarvinSessionsExtractor.d.ts.map

package/dist/connectors/MarvinSessionsExtractor.js

@@ -0,0 +1,57 @@
+import { MarvinExtractor } from './MarvinExtractor.js';
+import MarvinTransformer from './marvin-transformer.js';
+export class MarvinSessionsExtractor extends MarvinExtractor {
+    static description = 'Reading sessions';
+    static recordTypes = ['reading-sessions'];
+    static default = true;
+    static defaultTransformer = MarvinTransformer;
+    async *extract() {
+        // Read all CSV rows first
+        const rows = [];
+        for await (const record of super.extract()) {
+            rows.push(record.data); // CSV data is in the data field
+        }
+        // Group rows by Session ID
+        const sessions = rows.reduce((acc, row) => {
+            const sessionId = row['Session ID'];
+            if (!acc[sessionId]) {
+                acc[sessionId] = [];
+            }
+            acc[sessionId].push(row);
+            return acc;
+        }, {});
+        // Aggregate session data
+        const reads = Object.values(sessions).map((session) => {
+            const aggregated = session.reduce((memo, values) => Object.entries(values).reduce((memo, [key, newValue]) => {
+                if (key === 'Part Time') {
+                    // Sum all part times for the session
+                    memo[key] = (Number.parseFloat(memo[key] || '0') + Number.parseFloat(newValue)).toString();
+                }
+                else if (key === 'Date Created') {
+                    // Use the latest date as session end time
+                    memo[key] = memo[key]
+                        ? new Date(Math.max(new Date(memo[key]).getTime(), new Date(newValue).getTime())).toISOString()
+                        : newValue;
+                }
+                else {
+                    // For other fields, use latest value (last-wins strategy)
+                    memo[key] = newValue;
+                }
+                return memo;
+            }, memo), {});
+            return aggregated;
+        });
+        // Filter out sessions without required fields and sort by Date Created
+        let finalReads = reads
+            .filter(read => read['Date Created'] && read['Session ID'])
+            .sort((a, b) => new Date(a['Date Created']).getTime() - new Date(b['Date Created']).getTime());
+        // Apply limit to final processed sessions (not raw CSV rows)
+        if (this.config.limit) {
+            finalReads = finalReads.slice(-this.config.limit);
+        }
+        // Yield each reading session as a record
+        for (const read of finalReads) {
+            yield this.createRecord(read);
+        }
+    }
+}

package/dist/connectors/marvin-transformer.d.ts

@@ -0,0 +1,13 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { ActionAndChildren } from '@chronicle.app/schema';
+export default class MarvinTransformer extends ChronicleTransformer {
+    static source: string;
+    transform(record: Record): Promise<ActionAndChildren[]>;
+    private buildReadAction;
+    private buildBook;
+    private buildAuthor;
+    private buildAgent;
+    private buildAnnotationActions;
+    private buildAnnotationBook;
+}
+//# sourceMappingURL=marvin-transformer.d.ts.map

package/dist/connectors/marvin-transformer.js

@@ -0,0 +1,131 @@
+import { ChronicleTransformer, selfAgent } from '@chronicle.app/etl';
+export default class MarvinTransformer extends ChronicleTransformer {
+    static source = 'marvin';
+    async transform(record) {
+        const actions = [];
+        if (record.extraction.recordType === 'reading-sessions') {
+            actions.push(...this.buildReadAction(record));
+        }
+        else if (record.extraction.recordType === 'annotations') {
+            actions.push(...this.buildAnnotationActions(record));
+        }
+        return actions;
+    }
+    buildReadAction(record) {
+        const { data } = record;
+        // add "Part Time" (seconds) to "Date Created" to get "endTime"
+        const startTime = new Date(new Date(data['Date Created']).getTime() - Number.parseFloat(data['Part Time']) * 1000);
+        const obj = {
+            '@type': 'ReadAction',
+            '@key': ['@type', 'source', 'sourceId'],
+            startTime,
+            endTime: new Date(data['Date Created']),
+            source: 'marvin',
+            sourceId: data['Session ID'],
+            agent: this.buildAgent(),
+            object: this.buildBook(record),
+        };
+        return [obj];
+    }
+    buildBook(record) {
+        const { data } = record;
+        return {
+            '@type': 'Book',
+            '@key': ['@type', 'source', 'name', 'author.name'],
+            name: data['Book Title'],
+            source: 'marvin',
+            sourceId: data['Book Title'], // Use title as sourceId since no unique book ID
+            author: [this.buildAuthor(record)],
+        };
+    }
+    buildAuthor(record) {
+        const { data } = record;
+        // Properly unescape the author name (Marvin exports with comma escaping)
+        const authorName = data['Book Author'].replaceAll('\\,', ',');
+        return {
+            '@type': 'Person',
+            '@key': ['@type', 'source', 'name'],
+            name: authorName,
+            source: 'marvin',
+            sourceId: authorName, // Use cleaned name as sourceId
+        };
+    }
+    buildAgent() {
+        // The Marvin export carries no owner identity at all, so the self is the
+        // per-source singleton — merged into the real person through "@me",
+        // never a fabricated name.
+        return selfAgent({ source: 'marvin' });
+    }
+    buildAnnotationActions(record) {
+        const { data } = record;
+        const actions = [];
+        // Parse the date
+        const timestamp = new Date(data.Date || data.Created);
+        // Unescape author name
+        const authorName = data.Author ? data.Author.replaceAll('\\,', ',') : 'Unknown Author';
+        // Create the book that contains the content
+        const sourceBook = this.buildAnnotationBook(data, authorName);
+        // Create quotation first if it exists (so comment can reference it)
+        let quotation;
+        if (data.HighlightText) {
+            quotation = {
+                '@type': 'Quotation',
+                '@key': ['@type', 'source', 'sourceId'],
+                body: data.HighlightText,
+                source: 'marvin',
+                sourceId: data.ID,
+                isPartOf: [sourceBook],
+            };
+            const quoteAction = {
+                '@type': 'QuoteAction',
+                '@key': ['@type', 'source', 'sourceId'],
+                timestamp,
+                source: 'marvin',
+                sourceId: data.ID,
+                agent: this.buildAgent(),
+                result: quotation,
+            };
+            actions.push(quoteAction);
+        }
+        // Handle annotation (EntryText)
+        if (data.EntryText) {
+            const comment = {
+                '@type': 'Comment',
+                '@key': ['@type', 'source', 'sourceId'],
+                description: data.EntryText,
+                source: 'marvin',
+                sourceId: data.ID,
+                about: quotation ? [quotation] : [sourceBook], // Comment about quote if it exists, otherwise about book
+            };
+            const annotateAction = {
+                '@type': 'AnnotateAction',
+                '@key': ['@type', 'source', 'sourceId'],
+                timestamp,
+                source: 'marvin',
+                sourceId: data.ID,
+                agent: this.buildAgent(),
+                result: comment,
+            };
+            actions.push(annotateAction);
+        }
+        return actions;
+    }
+    buildAnnotationBook(data, authorName) {
+        return {
+            '@type': 'Book',
+            '@key': ['@type', 'source', 'name', 'author.name'],
+            name: data.Title,
+            source: 'marvin',
+            sourceId: data.Title,
+            author: [
+                {
+                    '@type': 'Person',
+                    '@key': ['@type', 'source', 'name'],
+                    name: authorName,
+                    source: 'marvin',
+                    sourceId: authorName,
+                },
+            ],
+        };
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,4 @@
+// Export extractors for plugin scanning. MarvinExtractor is the abstract CSV
+// base the two below share — not a strategy, so it stays unexported.
+export { MarvinAnnotationsExtractor } from './connectors/MarvinAnnotationsExtractor.js';
+export { MarvinSessionsExtractor } from './connectors/MarvinSessionsExtractor.js';

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@chronicle.app/marvin",
+  "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"
+  ],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Chronicle plugin for reading sessions and annotations from Marvin",
+  "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/marvin"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "csv-parse": "^5.6.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": {
+      "marvin": {
+        "strategies": {
+          "csv": {
+            "delivery": "export",
+            "recordTypes": [
+              "annotations",
+              "reading-sessions"
+            ],
+            "default": true
+          }
+        }
+      }
+    }
+  }
+}