@chronicle.app/google-reader 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,49 @@
+# @chronicle.app/google-reader
+
+Import personal actions from an unpacked Google Reader archive containing raw Reader API stream responses. This is a Chronicle workspace plugin.
+
+## Usage
+
+From a built Chronicle checkout:
+
+```bash
+chronicle extract google-reader --input /path/to/reader-archive
+chronicle extract google-reader --input /path/to/reader-archive \
+  --since 2010-01-01 --until 2010-12-31 --limit 1000
+```
+
+`--input` is a directory with this layout:
+
+```text
+reader-archive/
+  data/user-info.json
+  _raw_data/www.google.com-reader-api-0-stream-contents-user-<id>-<stream>.json
+```
+
+Each stream JSON has an `items` array. Items carry `id`, `title`, a microsecond `timestampUsec` string, and `categories` such as `user/123/state/com.google/read`. Optional `alternate`, `content`/`summary`, and `annotations` supply article URLs, bodies, and notes. Other archive files are ignored; this plugin does not parse OPML, ZIP files, preferences, or separate friend-activity files.
+
+The archive owner's ID comes from `user_id` in `data/user-info.json`; `user_name` and `email` provide optional profile details. Use `--user-id 123` to explicitly select your account, including when user info is missing. This also restricts stream filenames to that user. Only that account's states and annotations become actions, and only that account is linked to `@me`. The owner also links to a `google-account` identity using the Reader user ID and, when matching user info supplies an email, an `email` identity keyed by that address. These `sameAs` references resolve to the same entity on import; no email identity is inferred when the address is missing.
+
+`--since` and `--until` are inclusive bounds on the item's `timestampUsec`. `--limit` caps matching raw items across all files, not generated actions; `0` means unlimited. Files are processed in filename order, not chronological order. Invalid stream JSON or item timestamps fail the extraction rather than silently dropping a file.
+
+## Output
+
+- `read` → `ReadAction`
+- `broadcast` → `PublishAction`
+- `starred` → `LikeAction`
+- Owner annotations → `AnnotateAction` with a `Comment` result
+
+Actions link the owner to an `Article`, identified by its Reader item ID even when its URL is missing. Annotations are distinguished by article, author, and text; identical notes by the same author on the same article deduplicate because the supported annotation format has no separate note ID. Raw records include the individual item and stream metadata, without repeating the full stream.
+
+All actions on an item use its archive timestamp. Category state alone does not establish separate read, share, star, or annotation times; the output should not be interpreted as precise session timing.
+
+## Development
+
+```bash
+npm run build -w @chronicle.app/google-reader
+npm run test -w @chronicle.app/google-reader
+npm run lint -w @chronicle.app/google-reader
+npm run typecheck -w @chronicle.app/google-reader
+```
+
+Tests build small synthetic archives (a `user-info.json` and raw stream JSON files) in a temporary directory, run them through the extractor and transformer, and validate the output against the Chronicle schema. They never read the host's data or Google account and make no network requests.

package/dist/connectors/GoogleReaderExtractor.d.ts

@@ -0,0 +1,37 @@
+import { Extractor, Record } from '@chronicle.app/etl';
+import { z } from 'zod';
+import GoogleReaderTransformer from './GoogleReaderTransformer.js';
+export declare class GoogleReaderExtractor extends Extractor<typeof GoogleReaderExtractor> {
+    static source: string;
+    static description: string;
+    static delivery: "export";
+    static strategy: string;
+    static recordTypes: string[];
+    static default: boolean;
+    static defaultTransformer: typeof GoogleReaderTransformer;
+    static schema: z.ZodObject<{
+        since: z.ZodOptional<z.ZodDate>;
+        until: z.ZodOptional<z.ZodDate>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    } & {
+        input: z.ZodString;
+        userId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        input: string;
+        userId?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+        limit?: number | undefined;
+    }, {
+        input: string;
+        userId?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+        limit?: number | undefined;
+    }>;
+    extract(): AsyncGenerator<Record>;
+    private processStreamFile;
+    private isPersonalUserAction;
+    determineCount(): Promise<number | null>;
+}
+//# sourceMappingURL=GoogleReaderExtractor.d.ts.map

package/dist/connectors/GoogleReaderExtractor.js

@@ -0,0 +1,128 @@
+import { Extractor } from '@chronicle.app/etl';
+import { readdir, readFile } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import { z } from 'zod';
+import GoogleReaderTransformer from './GoogleReaderTransformer.js';
+export class GoogleReaderExtractor extends Extractor {
+    static source = 'google-reader';
+    static description = 'Read, starred, and shared items from Takeout';
+    static delivery = 'export';
+    static strategy = 'takeout';
+    static recordTypes = ['stream-contents'];
+    static default = true;
+    static defaultTransformer = GoogleReaderTransformer;
+    static schema = Extractor.schema.extend({
+        input: z.string().describe('Path to the google-reader archive directory'),
+        userId: z.string().optional().describe('Specific user ID to filter for (optional)'),
+    });
+    async *extract() {
+        const config = this.config;
+        this.logger.verboseInfo('Starting Google Reader archive extraction', {
+            archivePath: config.input,
+            userId: config.userId,
+            limit: config.limit,
+        });
+        try {
+            // Load user info
+            const userInfoPath = join(config.input, 'data', 'user-info.json');
+            let userInfo = null;
+            try {
+                const userInfoContent = await readFile(userInfoPath, 'utf-8');
+                userInfo = JSON.parse(userInfoContent);
+                this.logger.info('Loaded user info', {
+                    userName: userInfo?.user_name,
+                    userId: userInfo?.user_id,
+                });
+            }
+            catch (error) {
+                this.logger.warn('Could not load user-info.json', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            const ownerId = config.userId ?? userInfo?.user_id;
+            if (!ownerId) {
+                throw new Error('Provide --user-id when data/user-info.json has no user_id');
+            }
+            const rawDataPath = join(config.input, '_raw_data');
+            const files = (await readdir(rawDataPath))
+                .sort()
+                .filter(file => file.startsWith('www.google.com-reader-api-0-stream-contents-user-') &&
+                (!config.userId || file.includes(`-user-${config.userId}-`)));
+            let totalProcessed = 0;
+            for (const file of files) {
+                if (this.shouldStopExtracting(totalProcessed))
+                    break;
+                // Stream sequentially so the global cap avoids reading later files.
+                // eslint-disable-next-line no-await-in-loop
+                for await (const record of this.processStreamFile(join(rawDataPath, file), ownerId, userInfo)) {
+                    yield record;
+                    totalProcessed++;
+                    if (this.shouldStopExtracting(totalProcessed))
+                        break;
+                }
+            }
+        }
+        catch (error) {
+            this.logger.error('Failed to process Google Reader archive', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw new Error(`Failed to process Google Reader archive: ${error}`);
+        }
+    }
+    async *processStreamFile(filePath, userId, userInfo) {
+        try {
+            const content = await readFile(filePath, 'utf-8');
+            const streamData = JSON.parse(content);
+            if (!streamData.items) {
+                this.logger.warn('Stream file has no items', { filePath });
+                return;
+            }
+            this.logger.info(`Processing ${streamData.items.length} items from stream`, {
+                streamTitle: streamData.title,
+                itemCount: streamData.items.length,
+            });
+            const { items, ...streamMetadata } = streamData;
+            for (const item of items) {
+                if (!this.isPersonalUserAction(item, userId))
+                    continue;
+                const timestamp = new Date(Number(item.timestampUsec) / 1000);
+                if (!Number.isFinite(timestamp.getTime())) {
+                    throw new TypeError(`Invalid timestampUsec for item ${item.id}`);
+                }
+                if (this.config.since && timestamp < this.config.since)
+                    continue;
+                if (this.config.until && timestamp > this.config.until)
+                    continue;
+                yield this.createRecord({
+                    type: 'stream-content',
+                    userId,
+                    userInfo,
+                    streamData: streamMetadata,
+                    item,
+                    filePath: basename(filePath),
+                }, {
+                    itemId: item.id,
+                    timestamp: item.timestampUsec,
+                });
+            }
+        }
+        catch (error) {
+            this.logger.error('Failed to process stream file', {
+                filePath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+    isPersonalUserAction(item, userId) {
+        if (!item.categories)
+            return false;
+        return (item.categories.some(category => ['read', 'broadcast', 'starred'].some(state => category === `user/${userId}/state/com.google/${state}`)) || Boolean(item.annotations?.some(annotation => annotation.userId === userId)));
+    }
+    async determineCount() {
+        let count = 0;
+        for await (const _record of this.extract())
+            count++;
+        return count;
+    }
+}

package/dist/connectors/GoogleReaderTransformer.d.ts

@@ -0,0 +1,11 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { ActionAndChildren } from '@chronicle.app/schema';
+export default class GoogleReaderTransformer extends ChronicleTransformer {
+    transform(record: Record): Promise<ActionAndChildren[]>;
+    private buildStreamContentActions;
+    private buildUser;
+    private buildArticle;
+    private classifyActions;
+    private convertTimestamp;
+}
+//# sourceMappingURL=GoogleReaderTransformer.d.ts.map

package/dist/connectors/GoogleReaderTransformer.js

@@ -0,0 +1,158 @@
+import { ChronicleTransformer, selfAgent } from '@chronicle.app/etl';
+export default class GoogleReaderTransformer extends ChronicleTransformer {
+    async transform(record) {
+        this.logger.debug('Transforming google-reader record', {
+            recordType: record.extraction.recordType,
+        });
+        const actions = [];
+        if (record.extraction.recordType === 'stream-contents') {
+            actions.push(...this.buildStreamContentActions(record));
+        }
+        this.logger.verboseInfo(`Generated ${actions.length} actions from google-reader record`);
+        return actions;
+    }
+    buildStreamContentActions(record) {
+        const actions = [];
+        const { item } = record.data;
+        if (!item.categories)
+            return actions;
+        const personalUserId = record.data.userId ?? record.data.userInfo?.user_id;
+        if (!personalUserId)
+            return actions;
+        const user = this.buildUser(personalUserId, record.data.userInfo);
+        const article = this.buildArticle(item);
+        // Detect action types from categories
+        const actionTypes = this.classifyActions(item, personalUserId);
+        // Convert microsecond timestamp to Date object
+        const timestamp = this.convertTimestamp(item.timestampUsec);
+        for (const actionType of actionTypes) {
+            switch (actionType) {
+                case 'ReadAction':
+                    actions.push({
+                        '@type': 'ReadAction',
+                        '@key': ['@type', 'source', 'sourceId', 'agent.sourceId'],
+                        source: 'google-reader',
+                        sourceId: item.id,
+                        timestamp,
+                        agent: user,
+                        object: article,
+                    });
+                    break;
+                case 'PublishAction':
+                    actions.push({
+                        '@type': 'PublishAction',
+                        '@key': ['@type', 'source', 'sourceId', 'agent.sourceId'],
+                        source: 'google-reader',
+                        sourceId: item.id,
+                        timestamp,
+                        agent: user,
+                        object: article,
+                    });
+                    break;
+                case 'LikeAction':
+                    actions.push({
+                        '@type': 'LikeAction',
+                        '@key': ['@type', 'source', 'sourceId', 'agent.sourceId'],
+                        source: 'google-reader',
+                        sourceId: item.id,
+                        timestamp,
+                        agent: user,
+                        object: article,
+                    });
+                    break;
+            }
+        }
+        // Handle annotations separately
+        if (item.annotations) {
+            const userAnnotations = item.annotations.filter((ann) => ann.userId === personalUserId);
+            for (const annotation of userAnnotations) {
+                const comment = {
+                    '@type': 'Comment',
+                    '@key': ['@type', 'source', 'body', 'about.0.sourceId', 'author.0.sourceId'],
+                    source: 'google-reader',
+                    body: annotation.content,
+                    author: [user],
+                    about: [article],
+                };
+                actions.push({
+                    '@type': 'AnnotateAction',
+                    '@key': ['@type', 'source', 'object.sourceId', 'agent.sourceId', 'result.body'],
+                    source: 'google-reader',
+                    timestamp,
+                    agent: user,
+                    object: article,
+                    result: comment,
+                });
+            }
+        }
+        // Article is already included as the object of each action
+        return actions;
+    }
+    buildUser(userId, userInfo) {
+        const profile = userInfo?.user_id === userId ? userInfo : null;
+        const email = profile?.email?.trim() || undefined;
+        const name = profile?.user_name;
+        const sameAs = [];
+        if (email) {
+            sameAs.push({
+                '@type': 'Agent',
+                '@key': ['@type', 'source', 'handle'],
+                source: 'email',
+                handle: email,
+                ...(name && { name }),
+            });
+        }
+        sameAs.push({
+            '@type': 'Agent',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'google-account',
+            sourceId: userId,
+            ...(name && { name }),
+        });
+        return selfAgent({
+            type: 'Agent',
+            source: 'google-reader',
+            sourceId: userId,
+            handle: email,
+            name,
+            sameAs,
+        });
+    }
+    buildArticle(item) {
+        const url = item.alternate?.[0]?.href || '';
+        return {
+            '@type': 'Article',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'google-reader',
+            sourceId: item.id,
+            ...(url && { url }),
+            name: item.title,
+            body: item.content?.content || item.summary?.content || '',
+            // Note: author field expects EntityAndChildren[] but we only have string
+            // Could create Agent entities for authors if needed
+        };
+    }
+    classifyActions(item, userId) {
+        const actions = [];
+        if (!item.categories)
+            return actions;
+        for (const category of item.categories) {
+            // Only match exact personal states, not friend states
+            if (category === `user/${userId}/state/com.google/read`) {
+                actions.push('ReadAction');
+            }
+            if (category === `user/${userId}/state/com.google/broadcast`) {
+                actions.push('PublishAction');
+            }
+            if (category === `user/${userId}/state/com.google/starred`) {
+                actions.push('LikeAction');
+            }
+        }
+        return actions;
+    }
+    convertTimestamp(timestampUsec) {
+        // Convert microseconds to milliseconds and create Date object
+        const milliseconds = Math.floor(Number.parseInt(timestampUsec) / 1000);
+        return new Date(milliseconds);
+    }
+}

package/dist/connectors/types.d.ts

@@ -0,0 +1,49 @@
+export interface GoogleReaderItem {
+    id: string;
+    title: string;
+    published: number;
+    updated: number;
+    timestampUsec: string;
+    crawlTimeMsec: string;
+    categories: string[];
+    alternate?: Array<{
+        href: string;
+        type: string;
+    }>;
+    content?: {
+        content: string;
+        direction?: string;
+    };
+    summary?: {
+        content: string;
+        direction?: string;
+    };
+    annotations?: Array<{
+        content: string;
+        author: string;
+        userId: string;
+    }>;
+    author?: string;
+    origin: {
+        streamId: string;
+        title: string;
+        htmlUrl?: string;
+    };
+}
+export interface GoogleReaderStream {
+    id: string;
+    title: string;
+    author?: string;
+    items: GoogleReaderItem[];
+}
+export interface UserInfo {
+    user_id: string;
+    email: string;
+    profile_id: string;
+    user_name: string;
+    public_user_name: string;
+    is_blogger_user: boolean;
+    signup_time_sec: number;
+    is_multi_login_enabled: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/connectors/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

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

package/dist/index.js

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

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@chronicle.app/google-reader",
+  "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",
+    "google-reader"
+  ],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Import personal actions from Google Reader archive streams",
+  "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/google-reader"
+  },
+  "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": {
+      "google-reader": {
+        "strategies": {
+          "takeout": {
+            "delivery": "export",
+            "recordTypes": [
+              "stream-contents"
+            ],
+            "default": true
+          }
+        }
+      }
+    }
+  }
+}