@chronicle.app/pinboard 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,62 @@
+# @chronicle.app/pinboard
+
+Chronicle plugin for pinboard
+
+## Installation
+
+```bash
+npm install @chronicle.app/pinboard
+```
+
+## Usage
+
+### Basic extraction
+
+```bash
+chronicle extract pinboard --api-key YOUR_API_KEY
+```
+
+### With date filtering
+
+```bash
+chronicle extract pinboard \
+  --api-key YOUR_API_KEY \
+  --since 2024-01-01 \
+  --until 2024-12-31 \
+  --limit 1000
+```
+
+## Configuration
+
+The extractor supports the following options:
+
+- `--api-key`: API key for authentication, in Pinboard's `username:TOKEN`
+  form. Without it, the key stored by `chronicle auth set pinboard` is used.
+- `--tag-blacklist`: Tags to exclude from extraction (default: `twitterfavs`)
+- `--since`: Extract records from this date onwards
+- `--until`: Extract records up to this date
+- `--limit`: Maximum number of records to extract
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the plugin
+npm run build
+```
+
+## API Endpoints
+
+TODO: Document the API endpoints used and response formats.
+
+## Schema
+
+TODO: Document what Chronicle schema types are generated from this data source.
+
+## Tests
+
+Tests serve synthetic posts from a local HTTP server on 127.0.0.1 and pass a
+fake API key. They never call Pinboard or read stored credentials: the
+credential store points at an empty temporary directory.

package/dist/connectors/PinboardExtractor.d.ts

@@ -0,0 +1,40 @@
+import { Extractor, Record } from '@chronicle.app/etl';
+import { z } from 'zod';
+import PinboardTransformer from './PinboardTransformer.js';
+export declare class PinboardExtractor extends Extractor<typeof PinboardExtractor> {
+    static source: string;
+    static description: string;
+    static delivery: "api";
+    static strategy: string;
+    static recordTypes: string[];
+    static default: boolean;
+    static temporality: "snapshot";
+    static defaultTransformer: typeof PinboardTransformer;
+    static schema: z.ZodObject<{
+        since: z.ZodOptional<z.ZodDate>;
+        until: z.ZodOptional<z.ZodDate>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    } & {
+        tagBlacklist: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+        apiKey: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        tagBlacklist: string[];
+        apiKey?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+        limit?: number | undefined;
+    }, {
+        apiKey?: string | undefined;
+        tagBlacklist?: string[] | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+        limit?: number | undefined;
+    }>;
+    private proxy;
+    /** The bookmark's `hash` — Pinboard's own id for the saved url, identical through any tool. */
+    keyOf(record: Record): string | null;
+    setup(): Promise<void>;
+    extract(): AsyncGenerator<Record>;
+    determineCount(): Promise<number | null>;
+}
+//# sourceMappingURL=PinboardExtractor.d.ts.map

package/dist/connectors/PinboardExtractor.js

@@ -0,0 +1,95 @@
+import { Extractor } from '@chronicle.app/etl';
+import { z } from 'zod';
+import PinboardTransformer from './PinboardTransformer.js';
+import PinboardProxy from '../utils/PinboardProxy.js';
+export class PinboardExtractor extends Extractor {
+    static source = 'pinboard';
+    static description = 'Bookmarks';
+    static delivery = 'api';
+    static strategy = 'api';
+    static recordTypes = ['bookmarks'];
+    static default = true;
+    // `/posts/all` re-reports every bookmark with its latest title, description,
+    // and tags each run, so it's a state re-read, not an append-only feed:
+    // attributes are sighted at read time rather than back-dated to the save
+    // instant, letting an edit (a retitled or retagged bookmark) supersede cleanly
+    // instead of colliding with the old value at that timestamp. The BookmarkAction
+    // keeps its true save date on the timeline. Pinboard is a live API, so each
+    // read is a genuine sighting and the default run-start asOfTime is correct.
+    // See Extractor.temporality.
+    static temporality = 'snapshot';
+    static defaultTransformer = PinboardTransformer;
+    static schema = Extractor.schema.extend({
+        tagBlacklist: z
+            .array(z.string())
+            .optional()
+            .default(['twitterfavs'])
+            .describe('Tags to exclude from extraction'),
+        apiKey: z
+            .string()
+            .optional()
+            .describe('Pinboard API key for authentication (auto-retrieved from stored credentials if not provided)'),
+    });
+    proxy;
+    /** The bookmark's `hash` — Pinboard's own id for the saved url, identical through any tool. */
+    keyOf(record) {
+        return record.data.hash ?? null;
+    }
+    async setup() {
+        const config = this.config;
+        this.proxy = new PinboardProxy(config.apiKey);
+        await this.proxy.initialize();
+    }
+    async *extract() {
+        const config = this.config;
+        try {
+            const posts = await this.proxy.getAllPosts({
+                fromdt: config.since,
+                todt: config.until,
+            });
+            this.logger.info(`Retrieved ${posts.length} posts from Pinboard`);
+            let totalCount = 0;
+            for (const post of posts) {
+                // Apply date filtering
+                const postDate = new Date(post.time);
+                if (config.since && postDate < config.since)
+                    continue;
+                if (config.until && postDate > config.until)
+                    continue;
+                // Apply tag blacklist
+                const postTags = new Set(post.tags.split(' ').filter((tag) => tag.length > 0));
+                if (config.tagBlacklist &&
+                    config.tagBlacklist.some(blacklistedTag => postTags.has(blacklistedTag))) {
+                    continue;
+                }
+                // Apply limit
+                if (this.shouldStopExtracting(totalCount)) {
+                    break;
+                }
+                const username = this.proxy.getUsername();
+                yield this.createRecord(post, {
+                    recordType: 'bookmarks',
+                    username,
+                });
+                totalCount++;
+            }
+        }
+        catch (error) {
+            this.logger.error('Error fetching Pinboard posts');
+            throw error;
+        }
+    }
+    async determineCount() {
+        try {
+            const config = this.config;
+            const posts = await this.proxy.getAllPosts({
+                fromdt: config.since,
+                todt: config.until,
+            });
+            return posts.length;
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/connectors/PinboardTransformer.d.ts

@@ -0,0 +1,10 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { ActionAndChildren } from '@chronicle.app/schema';
+export default class PinboardTransformer extends ChronicleTransformer {
+    transform(record: Record): Promise<ActionAndChildren[]>;
+    private buildBookmarkActions;
+    private buildWebpage;
+    private buildUser;
+    private buildTags;
+}
+//# sourceMappingURL=PinboardTransformer.d.ts.map

package/dist/connectors/PinboardTransformer.js

@@ -0,0 +1,85 @@
+import { ChronicleTransformer } from '@chronicle.app/etl';
+const SOURCE = 'pinboard';
+// Pinboard returns empty strings for an absent description/extended note. The
+// schema treats optional fields as absent-or-undefined, so coalesce to a trimmed
+// string or undefined and omit the field when there's nothing to set.
+function str(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+export default class PinboardTransformer extends ChronicleTransformer {
+    async transform(record) {
+        const actions = [];
+        if (record.extraction.recordType === 'bookmarks') {
+            actions.push(...this.buildBookmarkActions(record));
+        }
+        return actions;
+    }
+    buildBookmarkActions(record) {
+        const { data } = record;
+        const user = this.buildUser(record);
+        const tags = this.buildTags(record);
+        const webpage = this.buildWebpage(record, tags);
+        const bookmarkAction = {
+            '@type': 'BookmarkAction',
+            // The save itself is a discrete event: keep its true date on the timeline
+            // even though the snapshot sights the bookmark's mutable attributes now.
+            timestamp: new Date(data.time),
+            '@key': ['@type', 'source', 'sourceId'],
+            source: SOURCE,
+            sourceId: data.hash,
+            agent: user,
+            object: webpage,
+        };
+        return [bookmarkAction];
+    }
+    buildWebpage(record, tags) {
+        const { data } = record;
+        const webpage = {
+            '@type': 'Entity',
+            // Keyed to this source, not the bare `{url}` hub, because of the
+            // `@asserts` below: a completeness claim can only speak for its own
+            // source. On the shared hub, clearing the note here would also close
+            // another source's description for the same url (and their next crawl
+            // would close ours) — an invented history of values churning. The merge
+            // still happens: the `url` field mints the `{url}` hub regardless of key.
+            '@key': ['url', 'source'],
+            source: SOURCE,
+            url: data.href,
+            ...(str(data.description) && { name: str(data.description) }),
+            ...(str(data.extended) && { description: str(data.extended) }),
+            ...(tags.length > 0 && { about: tags }),
+        };
+        // `description` and `about` can be cleared on a later snapshot (the note
+        // emptied, all tags removed); the `'*'` default only covers predicates still
+        // present, so list them explicitly to close the old values on re-read.
+        webpage['@asserts'] = ['description', 'about'];
+        return webpage;
+    }
+    buildUser(record) {
+        const username = record.context.username;
+        return {
+            '@type': 'Person',
+            '@key': ['@type', 'source', 'handle'],
+            source: SOURCE,
+            handle: username,
+            name: username,
+            url: `https://pinboard.in/u:${username}/`,
+            sameAs: ['@me'],
+        };
+    }
+    buildTags(record) {
+        const { data } = record;
+        if (!data.tags)
+            return [];
+        const tagNames = data.tags.split(' ').filter((tag) => tag.length > 0);
+        return tagNames.map((tagName) => ({
+            '@type': 'Tag',
+            '@key': ['@type', 'source', 'handle'],
+            source: SOURCE,
+            handle: tagName,
+        }));
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/utils/PinboardProxy.d.ts

@@ -0,0 +1,32 @@
+import { ApiProxy } from '@chronicle.app/etl';
+export interface PinboardPost {
+    href: string;
+    description: string;
+    extended: string;
+    meta: string;
+    hash: string;
+    time: string;
+    shared: string;
+    toread: string;
+    tags: string;
+}
+export default class PinboardProxy extends ApiProxy {
+    private authToken;
+    private username;
+    getAccessToken(): string;
+    getUsername(): string;
+    constructor(accessToken?: string);
+    initialize(): Promise<void>;
+    private authParams;
+    getAllPosts(options?: {
+        fromdt?: Date;
+        todt?: Date;
+        tag?: string;
+    }): Promise<PinboardPost[]>;
+    getRecentPosts(options?: {
+        tag?: string;
+        count?: number;
+    }): Promise<PinboardPost[]>;
+    getAllTags(): Promise<Record<string, number>>;
+}
+//# sourceMappingURL=PinboardProxy.d.ts.map

package/dist/utils/PinboardProxy.js

@@ -0,0 +1,81 @@
+import { ApiProxy } from '@chronicle.app/etl';
+import { resolveCredentials } from '@chronicle.app/auth';
+export default class PinboardProxy extends ApiProxy {
+    // Pinboard authenticates with an `auth_token` query parameter, not a bearer
+    // header, so the token lives here and the base's accessToken stays unset.
+    authToken;
+    username;
+    getAccessToken() {
+        return this.authToken;
+    }
+    getUsername() {
+        return this.username;
+    }
+    constructor(accessToken) {
+        super({
+            baseURL: 'https://api.pinboard.in',
+            headers: {
+                'User-Agent': 'Chronicle/1.0',
+            },
+        });
+        this.authToken = accessToken || '';
+        this.username = '';
+    }
+    async initialize() {
+        // `auth set` stores the token under the canonical `accessToken`;
+        // `apiKey` is kept as a fallback for any older stored credential.
+        const { accessToken } = await resolveCredentials('pinboard', {
+            accessToken: { from: ['accessToken', 'apiKey'] },
+        }, {
+            overrides: { accessToken: this.authToken || undefined },
+            errorMessage: 'Pinboard API key is required. Set it via --api-key or store in credentials.',
+        });
+        this.authToken = accessToken;
+        // Extract username from API key (format is username:token)
+        this.username = this.authToken.split(':')[0] || '';
+    }
+    authParams() {
+        return new URLSearchParams({
+            auth_token: this.authToken,
+            format: 'json',
+        });
+    }
+    async getAllPosts(options = {}) {
+        const params = this.authParams();
+        params.append('meta', 'yes');
+        if (options.fromdt) {
+            params.append('fromdt', options.fromdt.toISOString());
+        }
+        if (options.todt) {
+            params.append('todt', options.todt.toISOString());
+        }
+        if (options.tag) {
+            params.append('tag', options.tag);
+        }
+        return this.request({
+            url: `/v1/posts/all?${params.toString()}`,
+            method: 'GET',
+        });
+    }
+    async getRecentPosts(options = {}) {
+        const params = this.authParams();
+        params.append('meta', 'yes');
+        if (options.tag) {
+            params.append('tag', options.tag);
+        }
+        if (options.count) {
+            params.append('count', options.count.toString());
+        }
+        const data = await this.request({
+            url: `/v1/posts/recent?${params.toString()}`,
+            method: 'GET',
+        });
+        return data.posts;
+    }
+    async getAllTags() {
+        return this.request({
+            url: `/v1/tags/get?${this.authParams().toString()}`,
+            method: 'GET',
+        });
+    }
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@chronicle.app/pinboard",
+  "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",
+    "pinboard"
+  ],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Chronicle plugin for bookmarks from Pinboard",
+  "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/pinboard"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@chronicle.app/auth": "0.3.0",
+    "axios": "^1.7.9",
+    "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": {
+      "pinboard": {
+        "strategies": {
+          "api": {
+            "delivery": "api",
+            "recordTypes": [
+              "bookmarks"
+            ],
+            "default": true
+          }
+        }
+      }
+    }
+  }
+}