@chronicle.app/goodreads 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,95 @@
+# @chronicle.app/goodreads
+
+Chronicle plugin for goodreads
+
+## Installation
+
+```bash
+npm install @chronicle.app/goodreads
+```
+
+## Usage
+
+### Basic extraction
+
+```bash
+chronicle extract goodreads --input /path/to/goodreads_library_export.csv
+```
+
+### With date filtering
+
+```bash
+chronicle extract goodreads \
+  --input /path/to/goodreads_library_export.csv \
+  --since 2024-01-01 \
+  --until 2024-12-31 \
+  --limit 1000
+```
+
+## Configuration
+
+The extractor supports the following options:
+
+- `--input` (required): Path to the Goodreads library export CSV
+- `--display-name`: Your name, used as the reading agent's display label
+- `--user-id`: Your Goodreads review-list id — the `{id}-{slug}` (or bare numeric
+  id) in your My Books URL, e.g. `1234567-pat-example`. Keys the user agent on
+  the real id and gives each shelf its proper permalink; without it the agent and
+  shelves fall back to name-based identity.
+- `--since`: Extract records from this date onwards
+- `--until`: Extract records up to this date
+- `--limit`: Maximum number of records to extract
+
+## File Format
+
+The standard **Goodreads library export** CSV (Goodreads → _My Books_ → _Import
+and export_ → _Export Library_). The first row is the header; the columns used
+are `Book Id`, `Title`, `Author`, `Publisher`, `My Review`, `Bookshelves`,
+`Date Added`, `Date Read`, and `Exclusive Shelf`. Other columns are read through
+but not currently mapped.
+
+The export is a re-read of your current shelf state, so the extractor declares
+`temporality = 'snapshot'`: a book's mutable attributes (its review, the shelf
+it sits on) are sighted at read time rather than back-dated to its add/read date,
+so re-exporting after moving a book from _to-read_ to _read_ supersedes cleanly.
+
+## Schema
+
+Each row maps to a `Book` (keyed on the Goodreads `Book Id`) authored by a
+`Person`, plus actions by the exporting user keyed off the row's shelf and dates:
+
+| Goodreads row                     | Chronicle action | Notes                                             |
+| --------------------------------- | ---------------- | ------------------------------------------------- |
+| Any book with a `Date Added`      | `BookmarkAction` | The "saved it" signal, placed at the add date     |
+| `Exclusive Shelf` = `read`        | `CompleteAction` | Finish, placed at `Date Read` (falls back to add) |
+| `currently-reading` / `to-finish` | `ConsumeAction`  | In-progress status, undated (no session start)    |
+
+On the persistence side these fold into the derived `encountered` (every
+bookmarked book), `completed` (finished books), and `consuming` (in-progress)
+runs. The in-progress shelf is a status, not a reading session: Goodreads has no
+start time, so the bare `ConsumeAction` opens the `consuming` run with an unknown
+start, and a later finish closes it without asserting a reading interval.
+`ReadAction` is reserved for sources that report real sessions.
+
+The `Book` also carries metadata from the row: `My Review` → `description`,
+`Author` plus `Additional Authors` → the `author` list (translators, co-authors),
+`Publisher` → a name-keyed `Organization` on `publisher`, and `Number of Pages` →
+`pageCount` (an edition-level count). When an `ISBN13` is present it becomes a
+`sameAs` edge to the `isbn` namespace (a portable standard id), so the edition
+collapses onto the same book read through any other ISBN-bearing source.
+
+Each entry in `Bookshelves` becomes a `Collection` the book `isPartOf` — a shelf
+is a real user-owned list, not a free-text tag. With `--user-id` set, the shelf
+gets its true permalink (`…/review/list/{id}?shelf={name}`) and is keyed on that
+url, so the same shelf merges across books and stays distinct across users;
+without it, shelves are keyed on name. The exclusive shelf is dropped, since
+reading state is already the actions above. Because the export is a snapshot,
+removing a book from a shelf closes the membership on the next import.
+
+The 1–5 `My Rating` is not yet mapped.
+
+## Tests
+
+Tests write a small synthetic library export CSV to a temp directory and run it
+through the extractor and transformer, so they never read the host's Goodreads
+data or accounts.

package/dist/connectors/GoodreadsExtractor.d.ts

@@ -0,0 +1,18 @@
+import { CsvExtractor, Record } from '@chronicle.app/etl';
+import GoodreadsTransformer from './GoodreadsTransformer.js';
+export declare class GoodreadsExtractor extends CsvExtractor {
+    static source: string;
+    static description: string;
+    static delivery: "export";
+    static strategy: string;
+    static recordTypes: string[];
+    static default: boolean;
+    static temporality: "snapshot";
+    static defaultTransformer: typeof GoodreadsTransformer;
+    static schema: any;
+    /** The CSV's `Book Id` column — Goodreads' own book id, identical in any export. */
+    keyOf(record: Record): string | null;
+    constructor(config: any);
+    instantiateDefaultTransformer(): GoodreadsTransformer;
+}
+//# sourceMappingURL=GoodreadsExtractor.d.ts.map

package/dist/connectors/GoodreadsExtractor.js

@@ -0,0 +1,44 @@
+import { CsvExtractor, configForIo } from '@chronicle.app/etl';
+import { z } from 'zod';
+import GoodreadsTransformer from './GoodreadsTransformer.js';
+export class GoodreadsExtractor extends CsvExtractor {
+    static source = 'goodreads';
+    static description = 'Shelves and reading history from a CSV export';
+    static delivery = 'export';
+    static strategy = 'csv';
+    static recordTypes = ['shelves'];
+    static default = true;
+    // A Goodreads export is a re-read of current shelf state: re-exporting
+    // re-reports the same books with their latest shelf/review. So attributes are
+    // sighted at read time rather than back-dated to a Date Added/Read event,
+    // letting a book moving to-read → read supersede cleanly. See
+    // Extractor.temporality.
+    static temporality = 'snapshot';
+    static defaultTransformer = GoodreadsTransformer;
+    static schema = CsvExtractor.schema.extend({
+        displayName: z
+            .string()
+            .optional()
+            .describe("Your name, used as the reading agent's display label"),
+        userId: z
+            .string()
+            .optional()
+            .describe('Goodreads review-list id (the `{id}-{slug}` in your My Books URL, e.g. 1234567-pat-example). Enables real shelf permalinks.'),
+    });
+    /** The CSV's `Book Id` column — Goodreads' own book id, identical in any export. */
+    keyOf(record) {
+        return record.data['Book Id'] ?? null;
+    }
+    constructor(config) {
+        const ioConfig = configForIo(config);
+        super({
+            ...config,
+            ...ioConfig,
+            columns: true,
+            trimColumns: true,
+        });
+    }
+    instantiateDefaultTransformer() {
+        return new GoodreadsTransformer(this.config);
+    }
+}

package/dist/connectors/GoodreadsTransformer.d.ts

@@ -0,0 +1,48 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { ActionAndChildren } from '@chronicle.app/schema';
+export default class GoodreadsTransformer extends ChronicleTransformer {
+    transform(record: Record): Promise<ActionAndChildren[]>;
+    private buildGoodreadsActions;
+    private buildBook;
+    /**
+     * The ISBN-13 as a `sameAs` edge to the `isbn` namespace (a portable, standard
+     * id → protocol source), so this edition collapses onto the same book read
+     * through any other ISBN-bearing source. Carries the title so the edge still
+     * names the book if it's what mints it. The keyset is type-free — the ISBN
+     * names one work however a source typed it — and must stay identical across
+     * every plugin minting into the `isbn` namespace.
+     */
+    private buildIsbnSameAs;
+    /** Goodreads wraps ISBNs as `="9780…"`; return the bare 13-digit id, or none. */
+    private isbn13;
+    /**
+     * The user's custom shelves, as Collections the book `isPartOf`. A shelf is a
+     * real user-owned list with a permalink, not a free-text tag. The `Bookshelves`
+     * column repeats the exclusive shelf (the reading state, already modeled as
+     * actions), so drop it.
+     */
+    private buildShelves;
+    /**
+     * A shelf as a Collection. When the user's review-list id is configured we can
+     * build the real per-user permalink and key on it (distinct across users);
+     * otherwise the shelf is keyed on its name within the source.
+     */
+    private buildShelf;
+    private buildPublisher;
+    /**
+     * The primary author followed by any `Additional Authors` (translators,
+     * co-authors, illustrators — a comma-separated list), deduped by name.
+     */
+    private buildAuthors;
+    private buildAuthor;
+    private buildUser;
+    /**
+     * The user's numeric Goodreads id from config, the stable handle behind both
+     * the profile and shelf permalinks. Accepts either the bare id or the
+     * `{id}-{slug}` token (the slug is cosmetic and can change), normalizing to
+     * the numeric part.
+     */
+    private userId;
+    private parseDate;
+}
+//# sourceMappingURL=GoodreadsTransformer.d.ts.map

package/dist/connectors/GoodreadsTransformer.js

@@ -0,0 +1,225 @@
+import { ChronicleTransformer } from '@chronicle.app/etl';
+export default class GoodreadsTransformer extends ChronicleTransformer {
+    async transform(record) {
+        const actions = [];
+        if (record.extraction.recordType === 'shelves') {
+            actions.push(...(await this.buildGoodreadsActions(record)));
+        }
+        return actions;
+    }
+    async buildGoodreadsActions(record) {
+        const actions = [];
+        const { data } = record;
+        const user = this.buildUser();
+        const book = this.buildBook(data);
+        const dateAdded = data['Date Added'] ? this.parseDate(data['Date Added']) : undefined;
+        const dateRead = data['Date Read']?.trim() ? this.parseDate(data['Date Read']) : undefined;
+        // Adding a book to any shelf is a bookmark (the "saved it" signal), placed
+        // at when it was added.
+        if (dateAdded) {
+            actions.push({
+                '@type': 'BookmarkAction',
+                '@key': ['@type', 'source', 'object.sourceId', 'timestamp'],
+                source: 'goodreads',
+                agent: user,
+                object: book,
+                timestamp: dateAdded,
+            });
+        }
+        // The exclusive shelf is the book's reading state. `read` is a finish (a
+        // CompleteAction, which opens the `completed` run on the persistence side).
+        // An in-progress shelf is a status, not a session: Goodreads knows the book
+        // is being read but not when reading started, so it opens the `consuming`
+        // run with a bare, undated ConsumeAction (unknown start). ReadAction is
+        // reserved for genuine reading sessions with a real start.
+        const shelf = data['Exclusive Shelf'];
+        if (shelf === 'read') {
+            const finishedAt = dateRead ?? dateAdded;
+            actions.push({
+                '@type': 'CompleteAction',
+                '@key': ['@type', 'source', 'object.sourceId', 'timestamp'],
+                source: 'goodreads',
+                agent: user,
+                object: book,
+                ...(finishedAt && { timestamp: finishedAt }),
+            });
+        }
+        else if (shelf === 'currently-reading' || shelf === 'to-finish') {
+            actions.push({
+                '@type': 'ConsumeAction',
+                '@key': ['@type', 'source', 'object.sourceId'],
+                source: 'goodreads',
+                agent: user,
+                object: book,
+            });
+        }
+        return actions;
+    }
+    buildBook(data) {
+        const book = {
+            '@type': 'Book',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'goodreads',
+            sourceId: data['Book Id'],
+            name: data.Title,
+            url: `https://www.goodreads.com/book/show/${data['Book Id']}`,
+        };
+        const review = data['My Review']?.trim();
+        if (review)
+            book.description = review;
+        const authors = this.buildAuthors(data.Author, data['Additional Authors']);
+        if (authors.length > 0)
+            book.author = authors;
+        const pages = Number.parseInt(data['Number of Pages'], 10);
+        if (Number.isFinite(pages) && pages > 0)
+            book.pageCount = pages;
+        const shelves = this.buildShelves(data.Bookshelves, data['Exclusive Shelf']);
+        if (shelves.length > 0) {
+            book.isPartOf = shelves;
+            // A book removed from all custom shelves drops `isPartOf` from the payload,
+            // which the snapshot `'*'` default wouldn't close — list it so un-shelving
+            // closes the old memberships.
+            book['@asserts'] = ['isPartOf'];
+        }
+        const publisher = data.Publisher?.trim();
+        if (publisher)
+            book.publisher = [this.buildPublisher(publisher)];
+        const isbn13 = this.isbn13(data.ISBN13);
+        if (isbn13)
+            book.sameAs = [this.buildIsbnSameAs(isbn13, data.Title)];
+        return book;
+    }
+    /**
+     * The ISBN-13 as a `sameAs` edge to the `isbn` namespace (a portable, standard
+     * id → protocol source), so this edition collapses onto the same book read
+     * through any other ISBN-bearing source. Carries the title so the edge still
+     * names the book if it's what mints it. The keyset is type-free — the ISBN
+     * names one work however a source typed it — and must stay identical across
+     * every plugin minting into the `isbn` namespace.
+     */
+    buildIsbnSameAs(isbn13, title) {
+        return {
+            '@type': 'Book',
+            '@key': ['source', 'sourceId'],
+            source: 'isbn',
+            sourceId: isbn13,
+            name: title,
+        };
+    }
+    /** Goodreads wraps ISBNs as `="9780…"`; return the bare 13-digit id, or none. */
+    isbn13(raw) {
+        const digits = (raw ?? '').replaceAll(/\D/g, '');
+        return digits.length === 13 ? digits : undefined;
+    }
+    /**
+     * The user's custom shelves, as Collections the book `isPartOf`. A shelf is a
+     * real user-owned list with a permalink, not a free-text tag. The `Bookshelves`
+     * column repeats the exclusive shelf (the reading state, already modeled as
+     * actions), so drop it.
+     */
+    buildShelves(bookshelves, exclusiveShelf) {
+        if (!bookshelves)
+            return [];
+        const exclusive = exclusiveShelf?.trim();
+        return bookshelves
+            .split(',')
+            .map(s => s.trim())
+            .filter(s => s && s !== exclusive)
+            .map(shelf => this.buildShelf(shelf));
+    }
+    /**
+     * A shelf as a Collection. When the user's review-list id is configured we can
+     * build the real per-user permalink and key on it (distinct across users);
+     * otherwise the shelf is keyed on its name within the source.
+     */
+    buildShelf(shelf) {
+        const userId = this.userId();
+        if (userId) {
+            return {
+                '@type': 'Collection',
+                '@key': ['@type', 'url'],
+                source: 'goodreads',
+                name: shelf,
+                url: `https://www.goodreads.com/review/list/${userId}?shelf=${encodeURIComponent(shelf)}`,
+            };
+        }
+        return {
+            '@type': 'Collection',
+            '@key': ['@type', 'source', 'name'],
+            source: 'goodreads',
+            name: shelf,
+        };
+    }
+    buildPublisher(name) {
+        return {
+            '@type': 'Organization',
+            '@key': ['@type', 'source', 'name'],
+            source: 'goodreads',
+            name,
+        };
+    }
+    /**
+     * The primary author followed by any `Additional Authors` (translators,
+     * co-authors, illustrators — a comma-separated list), deduped by name.
+     */
+    buildAuthors(primary, additional) {
+        const names = [primary ?? '', ...(additional ?? '').split(',')]
+            .map(n => n.trim())
+            .filter(n => n.length > 0);
+        return [...new Set(names)].map(name => this.buildAuthor(name));
+    }
+    buildAuthor(authorName) {
+        return {
+            '@type': 'Person',
+            '@key': ['@type', 'source', 'name'],
+            source: 'goodreads',
+            name: authorName,
+        };
+    }
+    buildUser() {
+        const displayName = this.config.displayName?.trim();
+        // The numeric Goodreads id is the user's real, stable identity. When it's
+        // configured, key on it (and link the profile) so the agent survives a
+        // display-name change and stays distinct across imported users; the name is
+        // then just an optional label. Without an id we can only key on the name.
+        const userId = this.userId();
+        if (userId) {
+            return {
+                '@type': 'Person',
+                '@key': ['@type', 'source', 'sourceId'],
+                source: 'goodreads',
+                sourceId: userId,
+                ...(displayName && { name: displayName }),
+                url: `https://www.goodreads.com/user/show/${userId}`,
+                sameAs: ['@me'],
+            };
+        }
+        return {
+            '@type': 'Person',
+            '@key': ['@type', 'source', 'name'],
+            source: 'goodreads',
+            name: displayName || 'Unknown User',
+            sameAs: ['@me'],
+        };
+    }
+    /**
+     * The user's numeric Goodreads id from config, the stable handle behind both
+     * the profile and shelf permalinks. Accepts either the bare id or the
+     * `{id}-{slug}` token (the slug is cosmetic and can change), normalizing to
+     * the numeric part.
+     */
+    userId() {
+        const raw = this.config.userId?.trim();
+        return raw ? raw.split('-')[0] : undefined;
+    }
+    parseDate(dateString) {
+        if (!dateString)
+            return new Date();
+        // Handle Goodreads date format: YYYY/MM/DD
+        const parts = dateString.split('/');
+        if (parts.length === 3) {
+            return new Date(Number.parseInt(parts[0]), Number.parseInt(parts[1]) - 1, Number.parseInt(parts[2]));
+        }
+        return new Date(dateString);
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,2 @@
+export { GoodreadsExtractor } from './connectors/GoodreadsExtractor.js';
+export { default as GoodreadsTransformer } from './connectors/GoodreadsTransformer.js';

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@chronicle.app/goodreads",
+  "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",
+    "goodreads"
+  ],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Chronicle plugin for reading history and book data from Goodreads",
+  "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/goodreads"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "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": {
+      "goodreads": {
+        "strategies": {
+          "csv": {
+            "delivery": "export",
+            "recordTypes": [
+              "shelves"
+            ],
+            "default": true
+          }
+        }
+      }
+    }
+  }
+}