@chronicle.app/lastfm 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,156 @@
+# @chronicle.app/lastfm
+
+Chronicle plugin for Last.fm music listening history and loved tracks.
+
+## Installation
+
+```bash
+npm install @chronicle.app/lastfm
+```
+
+## Authentication
+
+The plugin supports multiple authentication methods:
+
+### OAuth Session (Recommended)
+
+1. Obtain a session key from Last.fm using their OAuth flow
+2. Use the session key with the `--access-token` flag
+
+### API Key
+
+Use a traditional Last.fm API key with the `--api-key` flag
+
+### Stored Credentials
+
+The plugin automatically retrieves stored credentials from Chronicle's credential manager when available.
+
+## Usage
+
+### Extract recent listening history
+
+```bash
+# Short form (recommended)
+chronicle extract lastfm --type listens --limit 500
+
+# Full form (select the strategy explicitly)
+chronicle extract lastfm --strategy api --type listens --limit 500
+```
+
+### Extract friends
+
+```bash
+chronicle extract lastfm --type friends
+```
+
+### Extract loved tracks
+
+```bash
+chronicle extract lastfm --type loved-tracks --limit 100
+```
+
+### With API key authentication
+
+```bash
+chronicle extract lastfm --type listens \
+  --api-key YOUR_API_KEY \
+  --username your_lastfm_username \
+  --since 2024-01-01 \
+  --limit 1000
+```
+
+### With OAuth session key
+
+```bash
+chronicle extract lastfm --type loved-tracks \
+  --access-token SESSION_KEY \
+  --username your_lastfm_username
+```
+
+## Configuration
+
+### Authentication Options
+
+- `--access-token`: OAuth session key from Last.fm
+- `--api-key`: Last.fm API key (alternative to OAuth)
+- `--username`: Last.fm username (auto-retrieved from stored credentials when available)
+
+### Extraction Options
+
+- `--since`: Extract records from this date onwards (YYYY-MM-DD format)
+- `--until`: Extract records up to this date (YYYY-MM-DD format)
+- `--limit`: Maximum number of records to extract (default: 100)
+
+### Output Options
+
+- `--output`: Output file path
+- `--loader`: Output format (json, csv, table, yaml)
+
+## Commands
+
+The extraction type is selected with `--type`; with no `--type`, every type is
+read:
+
+- `chronicle extract lastfm --type listens`: Recent listening history
+- `chronicle extract lastfm --type loved-tracks`: Loved/favorited tracks
+- `chronicle extract lastfm --type friends`: Friends (followed users)
+
+List the available types with `chronicle extract lastfm --help`.
+
+## Data Types
+
+The plugin generates the following Chronicle schema types:
+
+### Generated Chronicle Entities
+
+- `ListenAction`: a scrobble (recent track), timestamped at the play time
+- `LikeAction`: a loved/favorited track, timestamped when loved
+- `FollowAction`: the listener following a friend; no timestamp (Last.fm gives no
+  befriended date), sighted at read time by the snapshot `friends` extractor
+- `CreateAction`: a friend's Last.fm account registration, keyed on the account
+  handle and timestamped at their `registered` date (the account's
+  coming-into-being on `result`)
+- `Agent`: the listener and their friends, keyed on the Last.fm `handle` (the
+  canonical username), with real name, profile URL, and avatar `image` when
+  available
+- `MusicRecording`: track details, with cover `image` when available
+- `MusicAlbum`: album information (when available), with cover `image`
+- `MusicGroup`: artist information, with artist `image` when available
+
+Recordings, albums, and artists are deduplicated on their MusicBrainz ID when
+present, otherwise on their Last.fm URL.
+
+## API Integration
+
+The plugin uses the following Last.fm API endpoints:
+
+- `user.getRecentTracks`: Fetches listening history with automatic pagination
+- `user.getLovedTracks`: Fetches loved tracks with automatic pagination
+- `user.getFriends`: Fetches friends (followed users) with automatic pagination
+- `user.getinfo`: Retrieves user profile information
+
+### Features
+
+- Automatic pagination for large datasets
+- Rate limiting (200ms delay between requests)
+- Filters out "now playing" tracks and invalid timestamps
+- MusicBrainz ID-based deduplication when available
+- Date range filtering support
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the plugin
+npm run build
+
+# Run the tests
+npm test
+```
+
+The tests serve synthetic Last.fm API responses from a local HTTP server on
+127.0.0.1, pass fake credentials as config, and point the credential store at an
+empty temporary directory, so they never call Last.fm or read the host's stored
+credentials or accounts.

package/dist/auth/LastfmOAuthProvider.d.ts

@@ -0,0 +1,24 @@
+import { OAuthProvider, TokenResponse } from '@chronicle.app/auth';
+export declare class LastfmOAuthProvider extends OAuthProvider {
+    static providerId: string;
+    static authorizationUrl: string;
+    static tokenUrl: string;
+    static scopes: string[];
+    static requiresClientSecret: boolean;
+    /**
+     * Build the authorization URL for Last.fm
+     * https://www.last.fm/api/authentication
+     */
+    buildAuthUrl(): string;
+    /**
+     * Exchange authorization token for session key
+     * Last.fm uses a different flow than standard OAuth2
+     */
+    exchangeCodeForToken(token: string): Promise<TokenResponse>;
+    /**
+     * Generate API signature required by Last.fm
+     * Based on working omniauth-lastfm implementation
+     */
+    private generateApiSignature;
+}
+//# sourceMappingURL=LastfmOAuthProvider.d.ts.map

package/dist/auth/LastfmOAuthProvider.js

@@ -0,0 +1,79 @@
+import axios from 'axios';
+import { createHash } from 'node:crypto';
+import { OAuthProvider } from '@chronicle.app/auth';
+export class LastfmOAuthProvider extends OAuthProvider {
+    static providerId = 'lastfm';
+    static authorizationUrl = 'https://www.last.fm/api/auth';
+    static tokenUrl = 'https://ws.audioscrobbler.com/2.0/';
+    static scopes = []; // Last.fm doesn't use scopes
+    static requiresClientSecret = true;
+    /**
+     * Build the authorization URL for Last.fm
+     * https://www.last.fm/api/authentication
+     */
+    buildAuthUrl() {
+        const params = {
+            api_key: this.params.clientId,
+            cb: this.params.redirectUri,
+        };
+        const queryString = this.buildQueryString(params);
+        return `${LastfmOAuthProvider.authorizationUrl}?${queryString}`;
+    }
+    /**
+     * Exchange authorization token for session key
+     * Last.fm uses a different flow than standard OAuth2
+     */
+    async exchangeCodeForToken(token) {
+        try {
+            // Step 1: Get session key using auth.getSession
+            const paramsForSignature = {
+                method: 'auth.getSession',
+                api_key: this.params.clientId,
+                token,
+            };
+            // Add API signature required by Last.fm
+            const signature = this.generateApiSignature(paramsForSignature, this.params.clientSecret);
+            const allParams = {
+                ...paramsForSignature,
+                format: 'json',
+                api_sig: signature,
+            };
+            const sessionResponse = await axios.get(LastfmOAuthProvider.tokenUrl, {
+                params: allParams,
+            });
+            const sessionData = sessionResponse.data;
+            if (sessionData.error) {
+                throw new Error(`Last.fm API error: ${sessionData.message || sessionData.error}`);
+            }
+            if (!sessionData.session || !sessionData.session.key) {
+                throw new Error('No session key received from Last.fm');
+            }
+            // Last.fm returns a session key instead of access/refresh tokens
+            const tokens = {
+                provider: 'lastfm',
+                access_token: sessionData.session.key,
+                token_type: 'session',
+                created_at: new Date().toISOString(),
+                // Store the username from the session data
+                username: sessionData.session.name,
+            };
+            return tokens;
+        }
+        catch (error) {
+            if (axios.isAxiosError(error)) {
+                const message = error.response?.data?.message || error.message;
+                throw new Error(`Failed to get Last.fm session: ${message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Generate API signature required by Last.fm
+     * Based on working omniauth-lastfm implementation
+     */
+    generateApiSignature(params, secret) {
+        // Last.fm signature for auth.getSession: api_key{api_key}methodauth.getSessiontoken{token}{secret}
+        const signatureString = `api_key${params.api_key}method${params.method}token${params.token}${secret}`;
+        return createHash('md5').update(signatureString, 'utf8').digest('hex');
+    }
+}

package/dist/connectors/LastfmFriendsExtractor.d.ts

@@ -0,0 +1,41 @@
+import { Extractor, Record } from '@chronicle.app/etl';
+import { z } from 'zod';
+import LastfmTransformer from './LastfmTransformer.js';
+export declare class LastfmFriendsExtractor extends Extractor<typeof LastfmFriendsExtractor> {
+    static source: string;
+    static description: string;
+    static delivery: "api";
+    static strategy: string;
+    static recordTypes: string[];
+    static temporality: "snapshot";
+    static defaultTransformer: typeof LastfmTransformer;
+    static schema: z.ZodObject<{
+        since: z.ZodOptional<z.ZodDate>;
+        until: z.ZodOptional<z.ZodDate>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    } & {
+        accessToken: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        limit?: number | undefined;
+        accessToken?: string | undefined;
+        apiKey?: string | undefined;
+        username?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+    }, {
+        limit?: number | undefined;
+        accessToken?: string | undefined;
+        apiKey?: string | undefined;
+        username?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+    }>;
+    private proxy;
+    private username;
+    setup(): Promise<void>;
+    extract(): AsyncGenerator<Record>;
+    determineCount(): Promise<number | null>;
+}
+//# sourceMappingURL=LastfmFriendsExtractor.d.ts.map

package/dist/connectors/LastfmFriendsExtractor.js

@@ -0,0 +1,86 @@
+import { Extractor } from '@chronicle.app/etl';
+import { z } from 'zod';
+import { resolveCredentials } from '@chronicle.app/auth';
+import LastfmTransformer from './LastfmTransformer.js';
+import LastfmProxy from '../utils/LastfmProxy.js';
+export class LastfmFriendsExtractor extends Extractor {
+    static source = 'lastfm';
+    static description = 'Users you follow';
+    static delivery = 'api';
+    static strategy = 'api';
+    static recordTypes = ['friends'];
+    // The friends list is a re-read of current following state: re-running
+    // re-reports the same friends, and unfollowing drops one. The follow is
+    // sighted at read time (Last.fm gives no befriended date). See
+    // Extractor.temporality.
+    static temporality = 'snapshot';
+    static defaultTransformer = LastfmTransformer;
+    static schema = Extractor.schema.extend({
+        // OAuth token (from auth command)
+        accessToken: z
+            .string()
+            .optional()
+            .describe('OAuth session key from Last.fm (auto-retrieved from stored credentials if not provided)'),
+        // Traditional API key (alternative)
+        apiKey: z.string().optional().describe('Last.fm API key'),
+        username: z
+            .string()
+            .optional()
+            .describe('Last.fm username (auto-retrieved from stored credentials if not provided)'),
+    });
+    proxy;
+    username;
+    async setup() {
+        const config = this.config;
+        // Use the flag-provided key, else the stored client ID, else the stored
+        // OAuth session token.
+        const { authToken } = await resolveCredentials('lastfm', {
+            authToken: { from: ['clientId', 'accessToken'] },
+        }, {
+            overrides: { authToken: config.accessToken || config.apiKey },
+            errorMessage: 'Authentication required. Either:\n' +
+                '1. Run: chronicle auth login lastfm --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET\n' +
+                '2. Or use: --api-key YOUR_API_KEY for traditional auth\n' +
+                '3. Or use: --access-token TOKEN for OAuth session key',
+        });
+        // Get username from config or stored credentials
+        const { username } = await resolveCredentials('lastfm', {
+            username: { from: ['username'] },
+        }, {
+            overrides: { username: config.username },
+            errorMessage: 'Last.fm username is required. Either provide --username or authenticate with: chronicle auth login lastfm',
+        });
+        this.proxy = new LastfmProxy(authToken, username);
+        this.username = username;
+    }
+    async *extract() {
+        const config = this.config;
+        try {
+            // The listener whose friends these are (for the FollowAction agent).
+            const userInfo = await this.proxy.getUserInfo();
+            const friends = await this.proxy.getFriends({ limit: config.limit });
+            this.logger.info(`Retrieved ${friends.length} friends from Last.fm`);
+            for (const friend of friends) {
+                yield this.createRecord(friend, {
+                    recordType: 'friends',
+                    metadata: {
+                        username: this.username,
+                        userInfo,
+                    },
+                });
+            }
+        }
+        catch (error) {
+            this.logger.error('Error fetching Last.fm friends');
+            throw error;
+        }
+    }
+    async determineCount() {
+        try {
+            return await this.proxy.getFriendsCount();
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/connectors/LastfmLovedTracksExtractor.d.ts

@@ -0,0 +1,40 @@
+import { Extractor, Record } from '@chronicle.app/etl';
+import { z } from 'zod';
+import LastfmTransformer from './LastfmTransformer.js';
+export declare class LastfmLovedTracksExtractor extends Extractor<typeof LastfmLovedTracksExtractor> {
+    static source: string;
+    static description: string;
+    static delivery: "api";
+    static strategy: string;
+    static recordTypes: string[];
+    static defaultTransformer: typeof LastfmTransformer;
+    static schema: z.ZodObject<{
+        since: z.ZodOptional<z.ZodDate>;
+        until: z.ZodOptional<z.ZodDate>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    } & {
+        accessToken: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        limit?: number | undefined;
+        accessToken?: string | undefined;
+        apiKey?: string | undefined;
+        username?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+    }, {
+        limit?: number | undefined;
+        accessToken?: string | undefined;
+        apiKey?: string | undefined;
+        username?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+    }>;
+    private proxy;
+    private username;
+    setup(): Promise<void>;
+    extract(): AsyncGenerator<Record>;
+    determineCount(): Promise<number | null>;
+}
+//# sourceMappingURL=LastfmLovedTracksExtractor.d.ts.map

package/dist/connectors/LastfmLovedTracksExtractor.js

@@ -0,0 +1,84 @@
+import { Extractor } from '@chronicle.app/etl';
+import { z } from 'zod';
+import { resolveCredentials } from '@chronicle.app/auth';
+import LastfmTransformer from './LastfmTransformer.js';
+import LastfmProxy from '../utils/LastfmProxy.js';
+export class LastfmLovedTracksExtractor extends Extractor {
+    static source = 'lastfm';
+    static description = 'Loved tracks';
+    static delivery = 'api';
+    static strategy = 'api';
+    static recordTypes = ['loved-tracks'];
+    static defaultTransformer = LastfmTransformer;
+    static schema = Extractor.schema.extend({
+        // OAuth token (from auth command)
+        accessToken: z
+            .string()
+            .optional()
+            .describe('OAuth session key from Last.fm (auto-retrieved from stored credentials if not provided)'),
+        // Traditional API key (alternative)
+        apiKey: z.string().optional().describe('Last.fm API key'),
+        username: z
+            .string()
+            .optional()
+            .describe('Last.fm username (auto-retrieved from stored credentials if not provided)'),
+    });
+    proxy;
+    username;
+    async setup() {
+        const config = this.config;
+        // Use the flag-provided key, else the stored client ID, else the stored
+        // OAuth session token.
+        const { authToken } = await resolveCredentials('lastfm', {
+            authToken: { from: ['clientId', 'accessToken'] },
+        }, {
+            overrides: { authToken: config.accessToken || config.apiKey },
+            errorMessage: 'Authentication required. Either:\n' +
+                '1. Run: chronicle auth login lastfm --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET\n' +
+                '2. Or use: --api-key YOUR_API_KEY for traditional auth\n' +
+                '3. Or use: --access-token TOKEN for OAuth session key',
+        });
+        // Get username from config or stored credentials
+        const { username } = await resolveCredentials('lastfm', {
+            username: { from: ['username'] },
+        }, {
+            overrides: { username: config.username },
+            errorMessage: 'Last.fm username is required. Either provide --username or authenticate with: chronicle auth login lastfm',
+        });
+        this.proxy = new LastfmProxy(authToken, username);
+        this.username = username;
+    }
+    async *extract() {
+        const config = this.config;
+        try {
+            // Get user info for real name
+            const userInfo = await this.proxy.getUserInfo();
+            // Extract loved tracks
+            const lovedTracks = await this.proxy.getLovedTracks({
+                limit: config.limit,
+            });
+            this.logger.info(`Retrieved ${lovedTracks.length} loved tracks from Last.fm`);
+            for (const track of lovedTracks) {
+                yield this.createRecord(track, {
+                    recordType: 'loved-tracks',
+                    metadata: {
+                        username: this.username,
+                        userInfo,
+                    },
+                });
+            }
+        }
+        catch (error) {
+            this.logger.error('Error fetching Last.fm loved tracks');
+            throw error;
+        }
+    }
+    async determineCount() {
+        try {
+            return await this.proxy.getLovedCount();
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/connectors/LastfmRecentTracksExtractor.d.ts

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

package/dist/connectors/LastfmRecentTracksExtractor.js

@@ -0,0 +1,87 @@
+import { Extractor } from '@chronicle.app/etl';
+import { z } from 'zod';
+import { resolveCredentials } from '@chronicle.app/auth';
+import LastfmTransformer from './LastfmTransformer.js';
+import LastfmProxy from '../utils/LastfmProxy.js';
+export class LastfmRecentTracksExtractor extends Extractor {
+    static source = 'lastfm';
+    static description = 'Scrobbled listens';
+    static delivery = 'api';
+    static strategy = 'api';
+    static recordTypes = ['listens'];
+    static default = true;
+    static defaultTransformer = LastfmTransformer;
+    static schema = Extractor.schema.extend({
+        // OAuth token (from auth command)
+        accessToken: z
+            .string()
+            .optional()
+            .describe('OAuth session key from Last.fm (auto-retrieved from stored credentials if not provided)'),
+        // Traditional API key (alternative)
+        apiKey: z.string().optional().describe('Last.fm API key'),
+        username: z
+            .string()
+            .optional()
+            .describe('Last.fm username (auto-retrieved from stored credentials if not provided)'),
+    });
+    proxy;
+    username;
+    async setup() {
+        const config = this.config;
+        // Use the flag-provided key, else the stored client ID, else the stored
+        // OAuth session token.
+        const { authToken } = await resolveCredentials('lastfm', {
+            authToken: { from: ['clientId', 'accessToken'] },
+        }, {
+            overrides: { authToken: config.accessToken || config.apiKey },
+            errorMessage: 'Authentication required. Either:\n' +
+                '1. Run: chronicle auth login lastfm --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET\n' +
+                '2. Or use: --api-key YOUR_API_KEY for traditional auth\n' +
+                '3. Or use: --access-token TOKEN for OAuth session key',
+        });
+        // Get username from config or stored credentials
+        const { username } = await resolveCredentials('lastfm', {
+            username: { from: ['username'] },
+        }, {
+            overrides: { username: config.username },
+            errorMessage: 'Last.fm username is required. Either provide --username or authenticate with: chronicle auth login lastfm',
+        });
+        this.proxy = new LastfmProxy(authToken, username);
+        this.username = username;
+    }
+    async *extract() {
+        const config = this.config;
+        try {
+            // Get user info for real name
+            const userInfo = await this.proxy.getUserInfo();
+            // Extract recent tracks (listened)
+            const recentTracks = await this.proxy.getRecentTracks({
+                since: config.since,
+                until: config.until,
+                limit: config.limit,
+            });
+            this.logger.info(`Retrieved ${recentTracks.length} recent tracks from Last.fm`);
+            for (const track of recentTracks) {
+                yield this.createRecord(track, {
+                    recordType: 'listens',
+                    metadata: {
+                        username: this.username,
+                        userInfo,
+                    },
+                });
+            }
+        }
+        catch (error) {
+            this.logger.error('Error fetching Last.fm recent tracks');
+            throw error;
+        }
+    }
+    async determineCount() {
+        try {
+            return await this.proxy.getItemCount();
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/connectors/LastfmTransformer.d.ts

@@ -0,0 +1,15 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { ActionAndChildren } from '@chronicle.app/schema';
+export default class LastfmTransformer extends ChronicleTransformer {
+    transform(record: Record): Promise<ActionAndChildren[]>;
+    private buildFriendAction;
+    private buildJoinAction;
+    private buildListenAction;
+    private buildLoveAction;
+    private buildMusicRecording;
+    private buildMusicGroup;
+    private resolveUser;
+    private buildUser;
+    private buildLastfmAgent;
+}
+//# sourceMappingURL=LastfmTransformer.d.ts.map

package/dist/connectors/LastfmTransformer.js

@@ -0,0 +1,228 @@
+import { ChronicleTransformer, createImageObject } from '@chronicle.app/etl';
+// Last.fm returns each image at several sizes; pick the largest non-empty URL.
+function largestImage(images) {
+    if (!images?.length)
+        return undefined;
+    const order = ['mega', 'extralarge', 'large', 'medium', 'small'];
+    for (const size of order) {
+        const found = images.find(i => i.size === size && i['#text']?.trim());
+        if (found)
+            return found['#text'].trim();
+    }
+    return images.find(i => i['#text']?.trim())?.['#text'].trim();
+}
+export default class LastfmTransformer extends ChronicleTransformer {
+    async transform(record) {
+        const actions = [];
+        switch (record.extraction.recordType) {
+            case 'listens': {
+                actions.push(...this.buildListenAction(record));
+                break;
+            }
+            case 'loved-tracks': {
+                actions.push(...this.buildLoveAction(record));
+                break;
+            }
+            case 'friends': {
+                actions.push(...this.buildFriendAction(record));
+                break;
+            }
+        }
+        return actions;
+    }
+    // A Last.fm friend is a user the listener follows. Last.fm gives no
+    // befriended date, so the FollowAction carries no timestamp — it's sighted at
+    // read time by the snapshot extractor — and keys on the followed user's handle
+    // so re-reads supersede rather than duplicate.
+    buildFriendAction(record) {
+        const friend = record.data;
+        const friendAgent = this.buildLastfmAgent(friend.name, {
+            realname: friend.realname,
+            url: friend.url,
+            image: largestImage(friend.image),
+        });
+        const actions = [
+            {
+                '@type': 'FollowAction',
+                '@key': ['@type', 'source', 'sourceId'],
+                source: 'lastfm',
+                sourceId: friend.name,
+                agent: this.resolveUser(record),
+                object: friendAgent,
+            },
+        ];
+        const join = this.buildJoinAction(friend.name, friend.registered?.unixtime);
+        if (join) {
+            actions.push(join);
+        }
+        return actions;
+    }
+    // When a Last.fm account was created (its `registered` date). This is a real
+    // source event with a real timestamp, so it's a keyed action — not synthetic —
+    // keyed on the account handle so it's referenceable and re-reads supersede. The
+    // account's coming-into-being is origin-grade evidence carried on `result`; a
+    // bare handle reference is used so the friend's *current* avatar/name aren't
+    // back-dated to the registration instant — those stay on the FollowAction.
+    buildJoinAction(handle, unixtime) {
+        if (!unixtime)
+            return null;
+        const at = new Date(Number.parseInt(unixtime, 10) * 1000);
+        if (Number.isNaN(at.getTime()))
+            return null;
+        const ref = {
+            '@type': 'Agent',
+            '@key': ['@type', 'source', 'handle'],
+            source: 'lastfm',
+            handle,
+        };
+        return {
+            '@type': 'CreateAction',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'lastfm',
+            sourceId: handle,
+            timestamp: at,
+            agent: ref,
+            result: ref,
+        };
+    }
+    buildListenAction(record) {
+        const track = record.data;
+        const timestamp = new Date(Number.parseInt(track.date.uts) * 1000);
+        const action = {
+            '@type': 'ListenAction',
+            timestamp,
+            '@key': ['@type', 'source', 'timestamp'],
+            source: 'lastfm',
+            agent: this.resolveUser(record),
+            object: this.buildMusicRecording(track),
+        };
+        return [action];
+    }
+    buildLoveAction(record) {
+        const track = record.data;
+        const action = {
+            '@type': 'LikeAction',
+            timestamp: track.date ? new Date(Number.parseInt(track.date.uts) * 1000) : new Date(),
+            '@key': ['@type', 'source', 'timestamp'],
+            source: 'lastfm',
+            agent: this.resolveUser(record),
+            object: this.buildMusicRecording(track),
+        };
+        return [action];
+    }
+    buildMusicRecording(track) {
+        const artist = this.buildMusicGroup(track.artist, track.url);
+        // Last.fm serves a track's image as its album art.
+        const artUrl = largestImage(track.image);
+        // Use MBID for recording deduplication if available, otherwise fall back to URL
+        const recordingDedupeOn = track.mbid ? ['@type', 'source', 'sourceId'] : ['url'];
+        const recording = {
+            '@type': 'MusicRecording',
+            '@key': recordingDedupeOn,
+            url: track.url,
+            name: track.name,
+            artist: [artist],
+            ...(artUrl && { emblem: createImageObject({ url: artUrl }) }),
+        };
+        // Add MBID as sourceId if available
+        if (track.mbid) {
+            recording.sourceId = track.mbid;
+            recording.source = 'lastfm';
+        }
+        // Add album if available
+        if (track.album?.['#text']) {
+            const album = {
+                '@type': 'MusicAlbum',
+                '@key': track.album.mbid
+                    ? ['@type', 'source', 'sourceId']
+                    : ['@type', 'source', 'name', 'byArtist[*].name'],
+                source: 'lastfm',
+                name: track.album['#text'],
+                artist: [artist],
+                ...(artUrl && { emblem: createImageObject({ url: artUrl }) }),
+            };
+            // Add MBID as sourceId only if available
+            if (track.album.mbid) {
+                album.sourceId = track.album.mbid;
+            }
+            recording.inAlbum = album;
+        }
+        return recording;
+    }
+    buildMusicGroup(artistData, trackUrl) {
+        // Use MBID for artist deduplication if available, otherwise fall back to URL
+        const artistDedupeOn = artistData.mbid ? ['@type', 'source', 'sourceId'] : ['url'];
+        // Handle both name and #text fields from Last.fm API
+        const artistName = artistData.name || artistData['#text'];
+        // Derive artist URL from track URL if not provided
+        let artistUrl = artistData.url;
+        if (!artistUrl && trackUrl) {
+            // Remove the last two path segments from track URL to get artist URL
+            // e.g., "https://www.last.fm/music/Reese+Witherspoon/_/Break+Free+(with+Nick+Kroll)"
+            // becomes "https://www.last.fm/music/Reese+Witherspoon"
+            const urlParts = trackUrl.split('/');
+            if (urlParts.length >= 2) {
+                urlParts.pop(); // Remove track name
+                urlParts.pop(); // Remove "_" separator
+                artistUrl = urlParts.join('/');
+            }
+        }
+        const artUrl = largestImage(artistData.image);
+        const artist = {
+            '@type': 'MusicGroup',
+            '@key': artistDedupeOn,
+            source: 'lastfm',
+            name: artistName,
+            url: artistUrl,
+            ...(artUrl && { emblem: createImageObject({ url: artUrl }) }),
+        };
+        // Add MBID as sourceId if available
+        if (artistData.mbid) {
+            artist.sourceId = artistData.mbid;
+        }
+        return artist;
+    }
+    // The listener, from the canonical Last.fm username (user.getInfo), falling
+    // back to the resolved extractor config. Never a hardcoded handle.
+    resolveUser(record) {
+        const metadata = record.context?.metadata;
+        const userInfo = metadata?.userInfo;
+        const username = userInfo?.name ?? metadata?.username;
+        if (!username) {
+            throw new Error('Last.fm username could not be resolved for the listener');
+        }
+        // Only the listener (the account owner) is tagged as self; friends route
+        // through the same buildLastfmAgent and must not.
+        const user = this.buildUser(username, userInfo);
+        return { ...user, sameAs: [...(user.sameAs ?? []), '@me'] };
+    }
+    buildUser(username, userInfo) {
+        return this.buildLastfmAgent(username, {
+            realname: userInfo?.realname,
+            url: userInfo?.url || `https://last.fm/user/${username}`,
+            image: largestImage(userInfo?.image),
+        });
+    }
+    // A Last.fm user as an Agent, keyed on their handle (username), carrying the
+    // real name, profile URL, and avatar when available. Shared by the listener
+    // and their friends so both merge on the same handle.
+    buildLastfmAgent(handle, opts) {
+        const agent = {
+            '@type': 'Agent',
+            '@key': ['@type', 'source', 'handle'],
+            source: 'lastfm',
+            handle,
+        };
+        if (opts.url) {
+            agent.url = opts.url;
+        }
+        const realname = opts.realname?.trim();
+        if (realname) {
+            agent.name = realname;
+        }
+        if (opts.image) {
+            agent.emblem = createImageObject({ url: opts.image });
+        }
+        return agent;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { LastfmRecentTracksExtractor } from './connectors/LastfmRecentTracksExtractor.js';
+export { LastfmLovedTracksExtractor } from './connectors/LastfmLovedTracksExtractor.js';
+export { LastfmFriendsExtractor } from './connectors/LastfmFriendsExtractor.js';
+export { default as LastfmTransformer } from './connectors/LastfmTransformer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,8 @@
+export { LastfmRecentTracksExtractor } from './connectors/LastfmRecentTracksExtractor.js';
+export { LastfmLovedTracksExtractor } from './connectors/LastfmLovedTracksExtractor.js';
+export { LastfmFriendsExtractor } from './connectors/LastfmFriendsExtractor.js';
+export { default as LastfmTransformer } from './connectors/LastfmTransformer.js';
+// Register OAuth provider
+import { OAuthProviderRegistry } from '@chronicle.app/auth';
+import { LastfmOAuthProvider } from './auth/LastfmOAuthProvider.js';
+OAuthProviderRegistry.register(LastfmOAuthProvider);

package/dist/utils/LastfmProxy.d.ts

@@ -0,0 +1,127 @@
+import { ApiProxy } from '@chronicle.app/etl';
+export interface LastfmTrack {
+    name: string;
+    mbid: string;
+    url: string;
+    artist: {
+        name: string;
+        mbid: string;
+        url: string;
+        image?: Array<{
+            '#text': string;
+            size: string;
+        }>;
+    };
+    album?: {
+        '#text': string;
+        mbid: string;
+    };
+    image?: Array<{
+        '#text': string;
+        size: string;
+    }>;
+    date: {
+        uts: string;
+        '#text': string;
+    };
+    '@attr'?: {
+        nowplaying?: string;
+    };
+}
+export interface LastfmRecentTracksResponse {
+    recenttracks: {
+        track: LastfmTrack[];
+        '@attr': {
+            user: string;
+            totalPages: string;
+            page: string;
+            total: string;
+        };
+    };
+}
+export interface LastfmLovedTracksResponse {
+    lovedtracks: {
+        track: LastfmTrack[];
+        '@attr': {
+            user: string;
+            totalPages: string;
+            page: string;
+            total: string;
+        };
+    };
+}
+export interface LastfmFriend {
+    name: string;
+    realname?: string;
+    url: string;
+    country?: string;
+    playcount?: string;
+    image?: Array<{
+        '#text': string;
+        size: string;
+    }>;
+    registered?: {
+        unixtime: string;
+        '#text': number;
+    };
+}
+export interface LastfmFriendsResponse {
+    friends: {
+        user?: LastfmFriend[] | LastfmFriend;
+        '@attr': {
+            user: string;
+            totalPages: string;
+            page: string;
+            total: string;
+        };
+    };
+}
+export interface LastfmUser {
+    name: string;
+    realname?: string;
+    url?: string;
+    country?: string;
+    age?: string;
+    gender?: string;
+    subscriber?: string;
+    playcount?: string;
+    playlists?: string;
+    bootstrap?: string;
+    registered?: {
+        unixtime: string;
+        '#text': number;
+    };
+    image?: Array<{
+        '#text': string;
+        size: string;
+    }>;
+}
+export interface LastfmUserResponse {
+    user: LastfmUser;
+}
+export default class LastfmProxy extends ApiProxy {
+    private apiKey;
+    private username;
+    constructor(apiKey: string, username: string, baseUrl?: string);
+    initialize(): Promise<void>;
+    getRecentTracks(options?: {
+        since?: Date;
+        until?: Date;
+        limit?: number;
+    }): Promise<LastfmTrack[]>;
+    getLovedTracks(options?: {
+        limit?: number;
+    }): Promise<LastfmTrack[]>;
+    getFriends(options?: {
+        limit?: number;
+    }): Promise<LastfmFriend[]>;
+    private fetchFriends;
+    getFriendsCount(): Promise<number>;
+    private fetchRecentTracks;
+    private fetchLovedTracks;
+    private filterTracks;
+    getItemCount(): Promise<number>;
+    getLovedCount(): Promise<number>;
+    getUserInfo(): Promise<LastfmUser>;
+}
+//# sourceMappingURL=LastfmProxy.d.ts.map

package/dist/utils/LastfmProxy.js

@@ -0,0 +1,150 @@
+import { ApiProxy } from '@chronicle.app/etl';
+// Last.fm returns `friends.user` as an array, a bare object (single friend), or
+// omits it entirely (no friends). Normalize to an array.
+function normalizeFriends(response) {
+    const { user } = response.friends;
+    if (!user)
+        return [];
+    return Array.isArray(user) ? user : [user];
+}
+export default class LastfmProxy extends ApiProxy {
+    // Last.fm authenticates with an `api_key` query parameter, not a bearer
+    // header, so the key lives here and the base's accessToken stays unset.
+    apiKey;
+    username;
+    constructor(apiKey, username, baseUrl) {
+        super({
+            baseURL: baseUrl || 'https://ws.audioscrobbler.com/2.0',
+            headers: {
+                'User-Agent': 'Chronicle/1.0',
+            },
+            pageDelayMs: 200,
+        });
+        this.apiKey = apiKey;
+        this.username = username;
+    }
+    // The API key and username are resolved by the extractor's setup() and
+    // handed in via the constructor, so there is nothing left to load here.
+    async initialize() { }
+    async getRecentTracks(options = {}) {
+        return this.paginateByPage({
+            limit: options.limit,
+            fetchPage: async (page) => {
+                const response = await this.fetchRecentTracks(page, options);
+                return {
+                    items: this.filterTracks(response.recenttracks.track),
+                    totalPages: Number.parseInt(response.recenttracks['@attr'].totalPages),
+                };
+            },
+        });
+    }
+    async getLovedTracks(options = {}) {
+        return this.paginateByPage({
+            limit: options.limit,
+            fetchPage: async (page) => {
+                const response = await this.fetchLovedTracks(page);
+                return {
+                    items: response.lovedtracks.track,
+                    totalPages: Number.parseInt(response.lovedtracks['@attr'].totalPages),
+                };
+            },
+        });
+    }
+    async getFriends(options = {}) {
+        return this.paginateByPage({
+            limit: options.limit,
+            fetchPage: async (page) => {
+                const response = await this.fetchFriends(page);
+                return {
+                    items: normalizeFriends(response),
+                    totalPages: Number.parseInt(response.friends['@attr']?.totalPages ?? '1'),
+                };
+            },
+        });
+    }
+    async fetchFriends(page) {
+        return this.request({
+            url: '/',
+            method: 'GET',
+            params: {
+                method: 'user.getFriends',
+                user: this.username,
+                api_key: this.apiKey,
+                format: 'json',
+                page: page.toString(),
+                limit: '200',
+            },
+        });
+    }
+    async getFriendsCount() {
+        const response = await this.fetchFriends(1);
+        return Number.parseInt(response.friends['@attr']?.total ?? '0');
+    }
+    async fetchRecentTracks(page, options) {
+        const params = {
+            method: 'user.getRecentTracks',
+            user: this.username,
+            api_key: this.apiKey,
+            format: 'json',
+            page: page.toString(),
+            limit: '200',
+        };
+        if (options.since) {
+            params.from = Math.floor(options.since.getTime() / 1000).toString();
+        }
+        if (options.until) {
+            params.to = Math.floor(options.until.getTime() / 1000).toString();
+        }
+        return this.request({
+            url: '/',
+            method: 'GET',
+            params,
+        });
+    }
+    async fetchLovedTracks(page) {
+        return this.request({
+            url: '/',
+            method: 'GET',
+            params: {
+                method: 'user.getLovedTracks',
+                user: this.username,
+                api_key: this.apiKey,
+                format: 'json',
+                page: page.toString(),
+                limit: '200',
+            },
+        });
+    }
+    filterTracks(tracks) {
+        return tracks.filter(track => {
+            // Skip currently playing tracks (they don't have timestamps yet)
+            if (track['@attr']?.nowplaying)
+                return false;
+            // Skip tracks with invalid timestamps
+            if (track.date?.uts === '0')
+                return false;
+            return true;
+        });
+    }
+    async getItemCount() {
+        const response = await this.fetchRecentTracks(1, {});
+        return Number.parseInt(response.recenttracks['@attr'].total);
+    }
+    async getLovedCount() {
+        const response = await this.fetchLovedTracks(1);
+        return Number.parseInt(response.lovedtracks['@attr'].total);
+    }
+    async getUserInfo() {
+        const response = await this.request({
+            url: '/',
+            method: 'GET',
+            params: {
+                method: 'user.getinfo',
+                user: this.username,
+                api_key: this.apiKey,
+                format: 'json',
+            },
+        });
+        return response.user;
+    }
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@chronicle.app/lastfm",
+  "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",
+    "lastfm"
+  ],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Chronicle plugin for Last.fm listening history and loved tracks",
+  "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/lastfm"
+  },
+  "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": {
+      "lastfm": {
+        "strategies": {
+          "api": {
+            "delivery": "api",
+            "recordTypes": [
+              "friends",
+              "loved-tracks",
+              "listens"
+            ],
+            "default": true
+          }
+        }
+      }
+    }
+  }
+}